finance-mcp-server

An MCP server that gives any MCP client (Claude Desktop, Claude Code, etc.) real tools to manage your actual personal finances against a local SQLite ledger — no cloud account, no external service, no subscription, just a database file that lives on your machine. You can genuinely use this day-to-day: log expenses by talking to your MCP client, import your real bank statement, fix a typo'd entry, and ask questions like "am I over budget on dining out this month?".

Why

Most MCP server examples wrap a SaaS API as a toy demo. This one wraps a real, useful domain model instead: transactions, categories, and monthly budgets, with proper validation, aggregation queries, editable/deletable entries, and real-bank-statement CSV import — the kind of thing you'd actually want to run against your own money, not just a canned example.

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.

Getting your real data in

You don't have to type every transaction by hand. Most banks let you download your statement as a CSV — export one and ask your MCP client to import it, e.g.:

"Import the CSV at ~/Downloads/chase_september.csv — the date column is 'Transaction Date', amount is 'Amount', description is 'Description'"

Bank export formats vary a lot (some use one signed amount column, others split spending and deposits into separate "Debit"/"Credit" columns; date formats differ), so import_transactions_csv takes explicit column names rather than guessing — tell it what your bank's columns are called and it maps them. Malformed rows (a trailing "pending transactions" summary line, for example) are skipped and reported rather than aborting the whole import. If your bank shows expenses as positive numbers, pass flip_sign: true.

From there, everyday use is conversational: "add a $12 lunch at Chipotle today", "how much have I spent on groceries this month", "set my dining out budget to $150/month", "I mis-entered that coffee as $40, fix it to $4".

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.

Get started

Point FINANCE_MCP_DB at wherever you want your real ledger to live (it's created automatically on first use) and start talking to it through your MCP client — add transactions as they happen, or import a bank CSV export to backfill history in one go (see "Getting your real data in" below).

If you just want to poke around the tools before committing real data, python scripts/seed_demo_data.py seeds a separate database with ~3 months of fake sample transactions and budgets — useful for a first look, not meant to be your real ledger.

Architecture

src/finance_mcp/
├── db.py       # SQLite schema + query layer (stdlib sqlite3 only, no ORM)
├── csv_io.py   # Bank statement CSV import + ledger CSV export
└── server.py   # FastMCP tool definitions — thin wrappers around db.py / csv_io.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

26 tests cover the query layer (test_db.py), CSV import/export against real-shaped bank export data — signed-amount and debit/credit column layouts, US date formats, malformed rows, sign-flipped exports (test_csv_io.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, editing/deleting a transaction, 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