mcp-money

MCP server for personal finance tracking. Designed for AI assistants — track expenses, income, budgets, and get financial summaries through 16 MCP tools.

Uses PostgreSQL with Drizzle ORM. Auto-migrates on startup.

Requirements

• Bun runtime
• PostgreSQL 14+

Installation

bunx mcp-money

Configuration

Add to your MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "money": {
      "command": "bunx",
      "args": ["mcp-money"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Environment variables

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection string
MCP_MONEY_SCHEMA	No	mcp_money	PostgreSQL schema name
DEBUG	No	false	Enable SQL query logging to stderr

Tools (16)

Transactions

Tool	Description
add_transaction	Record an expense or income. Expenses stored as negative amounts. Tags created on-the-fly.
list_transactions	List with filters: date range, category, tag, currency. Supports limit/offset pagination.
update_transaction	Partial update of any field including tags.
delete_transaction	Hard delete a transaction.

Categories

Tool	Description
list_categories	List all categories grouped by type (expense/income).
create_category	Create a category with name, type, optional parent (one nesting level).
delete_category	Delete a category. Fails if transactions, budgets, or child categories reference it.

Tags

Tool	Description
list_tags	List all tags.
create_tag	Create a tag with a unique name.
delete_tag	Delete a tag and all transaction associations (CASCADE).

Summary

Tool	Description
get_summary	Financial summary for a date range: expenses by category, totals and averages per currency.

Budgets

Tool	Description
set_budget	Set or update a monthly budget for a category.
get_budget_status	Check budget vs actual spending for a month. Multi-currency aware.
delete_budget	Delete a budget by ID.

Utilities

Tool	Description
set_currency	Set the default currency for new transactions (e.g. USD, EUR, RUB).
health_check	Check DB connection, schema version, and statistics.

Multi-currency

Every transaction stores its own currency. The default currency (initially USD) can be changed via set_currency. Summaries and budget statuses group by currency — no cross-currency conversion.

Default categories

On first run, ~10 categories are seeded: Groceries, Restaurants, Transport, Entertainment, Utilities, Rent, Salary, Healthcare, Shopping, Other.

Development

bun install
bun run dev        # watch mode
bun test           # run tests

Requires a running PostgreSQL instance. Set DATABASE_URL in .env.

License

ISC