Local Expense Tracker

A simple local MCP (Model Context Protocol) server for tracking personal expenses using SQLite. This server exposes expense-related tools (add, list, summarize) that can be consumed by MCP-compatible clients such as Claude Desktop, Cursor, or other LLM hosts.

No HTTP server. No frontend. Just a clean local tool backend for LLMs.

---

Features

• Add expense entries with date, amount, category, subcategory, and notes
• List expenses within a date range
• Summarize expenses by category
• Local SQLite database (auto-created)
• Categories exposed as an MCP resource (expense://categories)
• Zero configuration beyond Python

---

Project Structure

expense_tracker/
│
├── server.py          # MCP server code
├── categories.json    # Expense categories (editable at runtime)
└── expenses.db        # SQLite database (auto-created)

---

Requirements

---

• Python 3.9+

• uv (recommended)

• fastmcp

---

Setup

---

1. Install uv (once)

pip install uv

Verify installation:

uv --version

2. Create a virtual environment

From the project directory:

uv venv

Activate it:

• Windows: .venv\Scripts\activate

• macOS / Linux: source .venv/bin/activate

3. Install dependencies

uv pip install fastmcp

---

Running the MCP Server

---

Start the server using:

uv run python server.py

Note: You will see no output. This is expected behavior as the server runs silently and waits for a compatible client (like Claude) to connect.

To stop the server: CTRL + C

Database Behavior

• The expenses.db file is automatically created on first run.

• Tables are created using CREATE TABLE IF NOT EXISTS.

• No manual database setup is required.

---

Available MCP Tools

---

add_expense

Adds a new expense entry to the database.

• date: string (format: YYYY-MM-DD)

• amount: number

• category: string

• subcategory: string (optional)

• note: string (optional)

list_expenses

Lists all expenses within a given date range.

• start_date: string (YYYY-MM-DD)

• end_date: string (YYYY-MM-DD)

summarize

Summarizes expenses by category.

• start_date: string (YYYY-MM-DD)

• end_date: string (YYYY-MM-DD)

• category: string (optional)

---

MCP Resources

---

expense://categories

Returns the contents of categories.json. The file is read fresh on every request, allowing category updates without restarting the server.

---

Using with Claude Desktop

---

Add the server to your claude_desktop_config.json (found in %APPDATA%\Claude on Windows or ~/Library/Application Support/Claude on macOS):

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--path",
        "C:/absolute/path/to/expense_tracker",
        "python",
        "server.py"
      ]
    }
  }
}

Note: Ensure you use absolute paths and forward slashes / even on Windows.

---

License

---

MIT License --- free to use, modify, and distribute.