Personal Finance MCP Server

A local MCP server for exploring fictional personal-finance transactions using SQLite.

Features

• get_transactions: filter transactions by date and category
• categorize_expense: suggest or update an expense category
• monthly_summary: income, expenses, net cash flow, category totals
• compare_spending: compare spending between two months
• Fictional sample data; no bank integration

Requirements

Python 3.11+

Install and run

Using uv:

uv sync
uv run python seed_db.py
uv run python -m finance_mcp.server

Using pip:

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
pip install -e .
python seed_db.py
python -m finance_mcp.server

The server uses MCP stdio transport, so it is normally launched by an MCP-compatible client rather than interacted with directly in a terminal.

MCP client configuration example

Adjust the directory to the location where you extracted this project:

{
  "mcpServers": {
    "personal-finance": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\personal_finance_mcp_server",
        "run",
        "python",
        "-m",
        "finance_mcp.server"
      ]
    }
  }
}

Tools

• get_transactions(start_date?, end_date?, category?, limit=100)
• categorize_expense(transaction_id, category?)
• monthly_summary(year, month)
• compare_spending(year_a, month_a, year_b, month_b)

Dates use YYYY-MM-DD. The demo data uses INR and is fictional. Set FINANCE_DB_PATH to override the SQLite file location.

Tests

uv sync --extra dev
uv run pytest

Re-seed demo data with python seed_db.py --reset.