Expense Tracker MCP

A local MCP server that lets an LLM (Claude Desktop, the FastMCP Inspector, or any MCP client) track your expenses and credits in a SQLite database on your machine.

Built with FastMCP.

Features

• Add, list, update, and delete expenses

• Track credits (money received) separately from expenses

• Category / subcategory enforcement — the LLM can only use categories and subcategories you've defined, so entries stay clean and consistent

• Per-category expense summary

• Running balance (total credited − total spent)

• All data stored locally in SQLite — nothing leaves your machine

Related MCP server: ExpenseTracker MCP Server

Project structure

expence-tracker-mcp/
├── server.py                              # entry point used by Claude Desktop / fastmcp CLI
├── src/expence_tracker_mcp/
│   ├── __init__.py                        # server: tools, resource, DB logic
│   ├── category.json                      # editable category → subcategory map
│   └── expenses.db                        # SQLite DB (auto-created on first run, gitignored)
├── pyproject.toml
└── uv.lock

Requirements

• Python >= 3.13

• uv

Setup

git clone <this-repo>
cd expence-tracker-mcp
uv sync

uv sync creates a .venv and installs fastmcp and its dependencies.

Running the server standalone

uv run server.py

Running the MCP Inspector (debugger)

Use this to interactively call the tools/resource in a browser before wiring it up to an LLM client.

uv run fastmcp dev inspector server.py

This prints a local URL (with an auth token) — open it in your browser, click Connect, then try the tools from the Tools tab.

Connecting to Claude Desktop

Add an entry to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ExpenseTracker": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/expence-tracker-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

Replace the path with the absolute path to this project on your machine, then fully quit and reopen Claude Desktop (Cmd+Q, not just close the window) to pick up the change.

Tools

Every write tool returns {"status": "ok", ...} on success or {"status": "error", "message": "..."} on failure (e.g. invalid category, record not found) instead of raising — so the calling LLM can see what went wrong and retry.

Resource

Customizing categories

Edit src/expence_tracker_mcp/category.json — it's read fresh on every tool call, so changes take effect immediately without restarting the server:

{
  "food": ["dining out", "snacks"],
  "travel": ["cab", "flight", "train", "fuel"],
  "rent": ["house rent", "office rent"],
  "groceries": []
}

• A category must be a top-level key in this file, or add_expense / update_expense will reject it.

• subcategory is required on add_expense.

• If a category's subcategory list is non-empty, the subcategory must be one of those exact values.

• If a category's subcategory list is empty (e.g. "groceries": []), any non-blank subcategory text is accepted — useful for categories too varied to enumerate.

This enforcement happens server-side in add_expense/update_expense, so invalid entries are rejected even if the LLM ignores the data://categories resource.

Database

SQLite database at src/expence_tracker_mcp/expenses.db, auto-created on first run with two tables:

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

CREATE TABLE credits(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    source TEXT DEFAULT '',
    note TEXT DEFAULT ''
);

The .db file is gitignored — each machine gets its own local data.

Inspecting the server

Check tool/resource counts without starting a full client:

uv run fastmcp inspect server.py