Expense Tracker MCP Server

A lightweight Model Context Protocol (MCP) server for recording, browsing, and summarizing expenses. It stores data locally in SQLite and exposes a curated category list as an MCP resource, so an MCP client can help keep spending records organized without relying on a hosted service.

Features

• Add expenses with a date, amount, category, optional subcategory, and note
• List expenses within an inclusive date range
• Summarize spending by category, with an optional category filter
• Read the available categories and subcategories from expense://categories
• Persist everything locally in expenses.db

Requirements

• Python 3.13 or newer
• uv (recommended)

Install

Clone the repository and install the project dependencies:

git clone https://github.com/ansh-rohilla/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server
uv sync

Run the server

Start the server with:

uv run python main.py

The SQLite database is created automatically at expenses.db in the project root on first run.

Configure an MCP client

Add the following server entry to your MCP client's configuration. Replace /absolute/path/to with the path where you cloned this repository.

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

For example, in Claude Desktop this entry belongs in claude_desktop_config.json. Restart the client after saving the configuration.

Available tools

add_expense

Adds an expense to the local database.

Parameter	Required	Description
date	Yes	Date of the expense, preferably YYYY-MM-DD
amount	Yes	Expense amount as a number
category	Yes	A top-level category such as food or transport
subcategory	No	A more specific category, such as groceries
note	No	Any useful context about the expense

Example request:

Add an expense of 450 on 2026-08-02 for groceries under food. Note: weekly vegetables.

list_expenses

Returns expenses whose dates fall within the inclusive range.

Parameter	Required	Description
start_date	Yes	Beginning of the date range (YYYY-MM-DD)
end_date	Yes	End of the date range (YYYY-MM-DD)

summarize

Returns total spending grouped by category for an inclusive date range.

Parameter	Required	Description
start_date	Yes	Beginning of the date range (YYYY-MM-DD)
end_date	Yes	End of the date range (YYYY-MM-DD)
category	No	Limit the summary to one category

Categories resource

The server provides expense://categories as JSON. It reads from categories.json, which you can customize to match your own budgeting system. Common top-level categories include food, transport, housing, utilities, health, education, entertainment, shopping, travel, investments, and more.

Data and privacy

Expenses remain on your machine in the local SQLite database. Back up expenses.db if you want to retain your records when moving or reinstalling the project. Because the database can contain personal financial information, avoid committing a populated copy to a public repository.

Project layout

.
├── main.py             # FastMCP server and expense tools
├── categories.json     # Available categories and subcategories
├── expenses.db         # Local SQLite database (created automatically)
├── pyproject.toml      # Project metadata and dependencies
└── uv.lock             # Locked dependency versions

License

No license has been specified yet. Add a license file before distributing or reusing this project publicly.