finance-mcp-server

An MCP server that gives any MCP client (Claude Desktop, Claude Code, etc.) tools to manage a personal finance ledger backed by local SQLite — no cloud account, no external service, just a single database file.

Why

Most MCP server examples wrap a SaaS API. This one wraps a real, useful domain model instead: transactions, categories, and monthly budgets, with proper validation, aggregation queries, and budget-vs-actual tracking — the kind of thing you'd actually want an assistant to reason over.

Related MCP server: Expense Tracker MCP Server

Tools exposed

Categories are created on the fly the first time you reference them — no separate setup step.

Install

git clone https://github.com/adeev-mardia/finance-mcp-server.git
cd finance-mcp-server
pip install -e ".[dev]"

Requires Python 3.10+.

Run it

As a standalone process (stdio transport):

finance-mcp-server
# or
python -m finance_mcp.server

Connect it to Claude Desktop / Claude Code

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp-server",
      "env": {
        "FINANCE_MCP_DB": "/absolute/path/to/finance.db"
      }
    }
  }
}

FINANCE_MCP_DB is optional — it defaults to data/finance.db relative to the package if unset.

Try it with demo data

python scripts/seed_demo_data.py   # seeds ~3 months of realistic transactions + budgets

Then ask your MCP client things like "what did I spend on groceries last month?" or "am I over budget on dining out this month?".

Architecture

src/finance_mcp/
├── db.py       # SQLite schema + query layer (stdlib sqlite3 only, no ORM)
└── server.py   # FastMCP tool definitions — thin wrappers around db.py

The persistence layer (db.py) has no dependency on the mcp package, so it's independently testable and reusable outside an MCP context (e.g. a CLI or web UI could sit on top of it too).

Testing

pip install -e ".[dev]"
pytest -v

11 tests cover the query layer directly (test_db.py) and the MCP tool functions as they'll actually be invoked by a client (test_server_tools.py), including edge cases like invalid dates, new-category creation, date-range filtering, and over-budget detection.

Design notes

• Signed amounts, not separate income/expense tables. A transaction's sign determines its kind; categories still carry a kind for aggregation, so "how much did I earn" and "how much did I spend" are simple WHERE clauses, not joins across tables.

• Categories are get-or-create. An MCP client (or the person prompting it) shouldn't need to pre-register categories before recording a transaction — friction there defeats the point of a conversational interface.

• No ORM. For a schema this small, stdlib sqlite3 keeps the whole persistence layer in one readable file and avoids a dependency that would otherwise dominate pip install -e ..

License

MIT