💰 Expense Tracker MCP Server

Talk to your expenses instead of typing them into a spreadsheet.

A local-first personal finance tracker built as a Model Context Protocol (MCP) server. It runs entirely on your own machine — no hosting, no cloud, no public endpoint — and connects to Claude Desktop over stdio, the transport MCP uses for a client launching a server as a local subprocess. Logging, editing, and analyzing expenses happens through plain conversation instead of a UI.

"I spent ₹450 on groceries today." → Claude Desktop launches this server as a local subprocess → calls a tool on it → a validated row lands in a SQLite file on your disk → "Got it — logged ₹450 under food/groceries."

No form. No dropdown. No app to open. No server to deploy or endpoint to secure, either — everything runs on your machine, under your own account, exactly like a CLI tool would. Just describe what happened, and an LLM turns it into a structured, validated database write — and can just as easily turn it back into an answer to "how much did I spend on food this month?"

Why this project exists

MCP (Model Context Protocol) is the open standard, introduced by Anthropic in late 2024, that lets AI applications like Claude call out to real tools and real data instead of just generating text. It's quickly become one of the standard ways serious AI applications are wired together — and this project is a from-scratch, hands-on implementation of one: a real server, exposing real tools, backed by a real database, connected to a real client.

It's small on purpose. The point isn't a big feature surface — it's demonstrating, concretely, the full loop: designing an MCP tool schema an LLM can call reliably, validating untrusted input from a model the same way you'd validate input from a user, and structuring the codebase so it doesn't fall over the moment it needs a second feature.

Related MCP server: Expense Tracker MCP Server

Architecture

flowchart LR
    U(["👤 You"]) -- "natural language" --> H["Claude Desktop\n(MCP Host + Client)"]
    H <-- "JSON-RPC 2.0 over stdio" --> S["Expense Tracker\nMCP Server (FastMCP)"]
    S --> DB[("SQLite\nexpenses.db")]
    S --> CAT["categories.json"]

    style H fill:#6E56CF,color:#fff
    style S fill:#2088FF,color:#fff
    style DB fill:#333,color:#fff

Claude Desktop is the host — the application you actually talk to. It embeds an MCP client, which speaks a standard JSON-RPC 2.0 protocol to this server over stdio (Claude Desktop launches it as a local subprocess). The server exposes two kinds of capability: tools the model can invoke (add_expense, summarize, ...) and a resource it can read (expense://categories).

What actually happens on one message

sequenceDiagram
    participant U as You
    participant C as Claude (Host)
    participant S as MCP Server
    participant D as SQLite

    U->>C: "I spent ₹450 on groceries today"
    C->>C: decides add_expense is the right tool
    C->>S: call_tool("add_expense", {date, amount, category, ...})
    S->>S: validate date, amount > 0, category exists
    alt input invalid
        S-->>C: ToolError with a clear message
        C-->>U: explains what was wrong
    else input valid
        S->>D: INSERT INTO expenses(...)
        D-->>S: new row id
        S-->>C: {"status": "ok", "id": 19}
        C-->>U: "Got it — logged ₹450 for groceries."
    end

The model never touches SQL and never sees your database file — it only ever sees the tool's declared inputs and outputs. Every validation rule lives on the server, not in the prompt, which is the entire point of doing this as an MCP server instead of just asking an LLM to "remember" your expenses in a chat.

How the server itself is layered

flowchart TD
    server["server.py\nFastMCP instance · tool & resource definitions\nthe ONLY module that knows MCP exists"]
    db["db.py\nsqlite3 access — zero MCP imports"]
    cat["categories.py\ncategory/subcategory rules"]
    val["validation.py\ndate & range rules"]
    cfg["config.py\npaths, env-var overridable"]

    server --> db
    server --> cat
    server --> val
    db --> cfg
    cat --> cfg
    val --> cfg

    style server fill:#2088FF,color:#fff
    style db fill:#333,color:#fff

db.py never imports fastmcp and never catches its own errors — a sqlite3.Error just propagates. Translating a failure into an MCP-friendly ToolError happens only in server.py. That's a deliberate boundary, not an accident: the data-access layer stays reusable and testable completely independently of the protocol sitting on top of it.

Features

Tools — functions the model can call:

Resources — data the client can read directly:

Engineering highlights

A few decisions worth calling out, because they're the difference between "it works" and "I'd trust this":

• Input validation treats the model like an untrusted caller. Every tool parameter is Annotated[type, Field(...)] — Pydantic constraints (Field(gt=0) on amounts) are enforced by FastMCP before a function body runs, and dates/categories are checked against real calendar rules and categories.json before anything touches the database.

• The data layer is protocol-agnostic by design. db.py doesn't know MCP exists. That single decision is what makes the test suite below possible without any mocking gymnastics.

• Configuration is environment-driven, not hardcoded. EXPENSE_TRACKER_DB_PATH and friends let the exact same code run against a real database or a disposable test one, with zero code changes.

• The test suite proves the server, not just the SQL. Unit tests hit db.py directly; the integration suite drives the server through FastMCP's real in-memory client — the same call path Claude Desktop uses — so schema validation and error translation are actually exercised, not assumed.

• Backward compatibility was a deliberate constraint, not an afterthought: when the project moved from a single script to a proper package (see ROADMAP.md, Phase 3), the root main.py was kept as a thin launcher specifically so an already-configured Claude Desktop setup wouldn't break.

Project structure

expense-tracker-mcp-server/
├── main.py                          # backward-compatible launcher
├── categories.json                  # category/subcategory reference data
├── expenses.db                      # SQLite database (gitignored)
├── exports/                         # CSV exports (gitignored)
├── pyproject.toml                   # deps, console-script entrypoint, pytest config
├── src/expense_tracker_mcp_server/
│   ├── __init__.py                  # real console-script entrypoint
│   ├── config.py                    # paths, env-var overridable
│   ├── db.py                        # sqlite3 access — no MCP imports
│   ├── categories.py                # category/subcategory validation
│   ├── validation.py                # date validation
│   └── server.py                    # FastMCP instance, tools, resource
├── tests/
│   ├── conftest.py                  # isolated throwaway DB per test
│   ├── test_db.py
│   ├── test_categories.py
│   ├── test_validation.py
│   └── test_server_integration.py   # via FastMCP's real client
├── .github/workflows/test.yml       # CI
└── ROADMAP.md                       # phase-by-phase build log

Getting started

Requires uv and Python 3.14+.

git clone https://github.com/<your-username>/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server
uv sync
uv run expense-tracker-mcp-server   # starts the MCP server over stdio

Connect it to Claude Desktop

Add this to Claude Desktop's claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/expense-tracker-mcp-server",
        "run", "expense-tracker-mcp-server"
      ]
    }
  }
}

Restart Claude Desktop, then just talk to it:

"Log ₹250 for groceries today." "What did I spend on food in August?" "Export my August expenses to CSV."

Configuration

Testing

uv run pytest -v

30 tests: unit tests against the data and validation layers directly, plus an integration suite that calls tools through FastMCP's real in-memory client rather than the raw Python functions — proving the server behavior, not just the SQL underneath. Every test runs against its own disposable SQLite file; nothing ever touches real data. Runs automatically on every push via GitHub Actions.

Roadmap

This project is being hardened in deliberate, documented phases — see ROADMAP.md for the full write-up of what's done, what's next, and the reasoning behind each decision.

What this project demonstrates

• Designing and implementing an MCP server from scratch (tools, a resource, schema design) with FastMCP

• Treating LLM-supplied input as untrusted, with real validation and clean error surfaces

• Layered architecture with a deliberate protocol boundary, not just "more files"

• A real, verified test suite (unit + protocol-level integration) with CI

• Environment-based configuration instead of hardcoded paths

• Writing documentation that's actually useful to someone other than the author

License

MIT — see LICENSE.

Author

Ansh Gautam — anshgautam1011@gmail.com