MCP 服务器

expense-tracker-mcp-server

Enables natural language expense tracking and management via Claude Desktop, supporting adding, listing, summarizing, updating, and deleting expenses with flexible date parsing and category filtering.

README

Expense Tracker MCP Server

A powerful Model Context Protocol (MCP) server for tracking and managing personal expenses. This server integrates with Claude Desktop to provide seamless expense management through natural language interactions.

Features

🛠️ Tools

add_expense: Add new expenses with flexible date parsing (supports "today", "yesterday", "Nov 27, 2025", etc.)
list_expenses: List expenses with filtering by category, date range, and natural language date queries
summarize_expenses: Get expense summaries by category with totals and percentages
update_expense: Modify existing expense records
delete_expense: Remove expense records by ID

📋 Resources

expense://categories: Access predefined expense categories and subcategories from categories.json

✨ Key Capabilities

Natural Language Date Support: Use phrases like "last week", "last month", "this year", "last 30 days"
SQLite Database: Lightweight and efficient local storage
Category Management: Pre-defined categories with subcategories for better organization
Flexible Filtering: Filter expenses by date range, category, or specific criteria
Rich Summaries: View spending patterns with category-wise breakdowns and percentages

Installation

Prerequisites

Python 3.8 or higher
uv package manager (recommended)
Claude Desktop

Steps

Clone the repository

git clone <your-repo-url>
cd Expense-Tracker-MCP-Server

Install dependencies

Using uv (recommended):

uv pip install -r requirements.txt

Or using pip:

pip install -r requirements.txt

Install to Claude Desktop

uv run fastmcp install claude-desktop main.py

Or manually add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json on Mac/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "Expense Tracker Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/Expense-Tracker-MCP-Server/main.py"
      ]
    }
  }
}

Restart Claude Desktop

Completely quit and restart Claude Desktop to load the MCP server.

Usage

Once installed, you can interact with the Expense Tracker directly in Claude Desktop using natural language:

Adding Expenses

"Add an expense of $45.50 for groceries yesterday"
"I spent $20 on lunch today in the Food category"
"Add expense: $100, Transport, Fuel, Nov 25, 2025, note: Monthly fuel"

Listing Expenses

"Show me all expenses from last week"
"List my Food expenses from this month"
"Show expenses from last 30 days"

Summarizing Expenses

"Summarize my expenses for last month"
"Show category-wise breakdown for this year"
"Summarize Food expenses from last week"

Updating Expenses

"Update expense ID 5, change amount to $55.50"
"Change expense 3's category to Transport"

Deleting Expenses

"Delete expense with ID 7"

Database Schema

The server uses SQLite with the following schema:

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT,
    note TEXT
);

Development

Running Locally

uv run fastmcp dev main.py

Project Structure

Expense-Tracker-MCP-Server/
├── main.py                 # Main MCP server code
├── categories.json         # Expense categories and subcategories
├── requirements.txt        # Python dependencies
├── pyproject.toml         # Project metadata
├── expenses.db            # SQLite database (auto-created)
└── README.md              # This file