Expense Tracker

This MCP server provides an AI-powered expense tracking engine that handles budgeting, expense ingestion, smart category detection, and affordability analytics, all exposed through the Model Context Protocol to enable safe, intelligent interactions with your financial data via compatible AI assistants.

How to use

You connect an MCP client to this server to manage budgets, add expenses, and retrieve insights. Use the client to create monthly budgets, add expenses with automatic category detection, check affordability before adding expenses, and view summaries or category breakdowns across time ranges. You can perform bulk expense additions, update or delete entries with safety prompts, and receive human-friendly guidance when inputs are unclear.

How to install

Prerequisites: ensure you have Python installed and a development environment ready. You will run the server locally using a simple MCP command.

Step 1: Clone the project into your workspace.

Step 2: Create and activate a Python virtual environment.

Step 3: Install dependencies from the required file.

Step 4: Start the MCP server using the standard development command.

Step 5: Access the server from your MCP client and begin issuing tools to manage budgets, expenses, affordability checks, and insights.

Claude Desktop Integration

If you use Claude Desktop, configure the MCP server connection as shown below. This enables Claude to launch and communicate with the local server.

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "dev",
        "/absolute/path/to/expense-tracker-mcp/server.py"
      ]
    }
  }
}

Notes on running in development

The server is designed to initialize the SQLite database automatically on startup, so there is no separate manual database setup required.

If you prefer a different startup flow, you can use the alternative development command to run the server in a testing environment.

Available tools

set_monthly_budget

Set total or category-based budgets for a given month.

get_remaining_budget

Check remaining money by month or by category.

list_budgets

View all configured budgets.

convert_to_category_budget

Transform a simple total budget into a detailed category-based budget.

add_expense

Add an expense with smart category detection and date parsing.

bulk_add_expenses

Add multiple expenses at once with validation and robust error handling.

update_expense

Safely update expense amount, category, date, or description with validation.

delete_expense

Safely delete an expense with a confirmation step.

get_category_info

Retrieve rules for categories and subcategories.

check_affordability

Predict impact of a prospective expense against current budgets.

monthly_summary

Provide spending summaries by month.

category_breakdown

Offer insights broken down by category.

remaining_days_info

Show insights with days remaining in the current period.

smart_lookup

Perform intelligent searches like "What did I spend on food last week?"