finance-mcp

An MCP server that turns an LLM into a personal bookkeeper: income/expense tracking in local SQLite with accounts, categories, day/week/month/year reports, monthly budgets and savings goals («откладывать»).

Packaged like its sibling ghostswap-mcp: run it with uv, install it as a flake package, or enable it as a NixOS service (services.finance-mcp).

Tools

Tool	Notes
list_accounts / add_account / balance	Wallets (cash/bank/card/deposit) with computed balances.
add_expense / add_income	Amount is a decimal string ("199.90"). Unknown categories are auto-created. Date defaults to today.
list_transactions / get_transaction / update_transaction / delete_transaction	Filter by month/week/year, kind, category, account.
report	Period: YYYY-MM-DD, YYYY-Www (ISO week), YYYY-MM or YYYY. Totals, per-category shares, subtotals, comparison with the previous period.
report_range	Arbitrary inclusive date range with per-week subtotals.
list_categories / add_category / rename_category / delete_category	Seeded with sane RU defaults; subcategories supported.
set_budget / remove_budget / budget_status	Monthly per-category spending limits, % used, over-budget flag.
add_goal / deposit / withdraw / list_goals / delete_goal	Savings goals. deposit books a real expense («накопления») so money aside leaves the balance; withdraw books it back as income.

Data storage

Everything lives in one SQLite database (WAL mode):

FINANCE_DB=/path/to/finance.db      # default: ~/.local/share/finance-mcp/finance.db

Amounts are stored as integer minor units (kopecks/cents) — no float drift. Dates are civil YYYY-MM-DD in server-local time.

Running

With uv (development)

git clone ssh://forgejo@git.desu.church:61488/eva/finance-mcp.git
cd finance-mcp
uv run finance-mcp                       # stdio (default)
uv run finance-mcp --transport streamable-http --host 127.0.0.1 --port 8080

As an MCP client (stdio)

{
  "mcpServers": {
    "finance": {
      "command": "uv",
      "args": ["run", "finance-mcp"],
      "cwd": "/path/to/finance-mcp",
      "env": { "FINANCE_DB": "/path/to/finance.db" }
    }
  }
}

Nix flake

nix run git+ssh://forgejo@git.desu.church:61488/eva/finance-mcp.git
nix build .    # -> ./result/bin/finance-mcp

NixOS module

The flake exposes nixosModules.default, running the server under systemd as streamable-http with a persistent StateDirectory:

{
  imports = [ inputs.finance-mcp.nixosModules.default ];

  services.finance-mcp = {
    enable = true;
    host = "127.0.0.1";
    port = 8080;
  };
}

The database lands in /var/lib/finance-mcp/finance.db. Options: transport, host, port, openFirewall, environmentFile, extraEnvironment, package.

License

MIT.