Expense Tracker MCP Server

A personal expense tracking system built with the Model Context Protocol (MCP). You talk to it in plain English through a chat interface, and it logs, retrieves, and summarises your expenses using a local SQLite database.

This project has two parts:

• main.py — the MCP server that holds all the tools and data logic
• client.py — a Streamlit chat interface that connects to the server and talks to GPT-4o-mini

---

What it can do

Expenses

• Add a new expense (date, amount, category, subcategory, note)
• List expenses for any date range
• Edit an existing expense by ID
• Delete an expense by ID
• Summarise spending by category and subcategory

Categories

• List all categories and subcategories
• Add, rename, or delete a category
• Add, rename, or delete a subcategory

Date understanding

• Understands plain English like "last week", "this month", "yesterday"
• Uses a get_date_info tool so the model always gets the correct current date — not its training data

---

Project structure

expense-tracker-mcp-server/
├── main.py             # MCP server — all tools live here
├── client.py           # Streamlit chat interface
├── categories.json     # Category and subcategory definitions
├── expenses.db         # SQLite database (created automatically on first run)
├── .env                # Your API key and paths (not committed to git)
├── .gitignore
└── pyproject.toml      # Dependencies managed by uv

---

Requirements

• Python 3.11 or higher
• uv — for managing the virtual environment and dependencies
• An OpenAI API key (uses gpt-4o-mini)
• Node.js — only needed if you want to use the MCP Inspector for debugging

---

Setup

1. Clone the repository

git clone https://github.com/07sada/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

2. Install uv

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -Lsf https://astral.sh/uv/install.sh | sh

3. Install dependencies

uv sync

This creates a .venv folder and installs everything from pyproject.toml.

4. Create your .env file

Create a file named .env in the project root with the following contents:

OPENAI_API_KEY=your-openai-api-key-here
UV_PATH=C:\Users\YourName\.local\bin\uv.exe
MCP_SERVER_PATH=D:\Projects\expense-tracker-mcp-server

How to find your uv path:

# Windows
where.exe uv

# macOS / Linux
which uv

Copy the full path into UV_PATH.

On macOS/Linux, UV_PATH is usually something like /home/yourname/.local/bin/uv or /usr/local/bin/uv.

5. Run the chat interface

uv run streamlit run client.py

Open your browser at http://localhost:8501. The app will connect to the MCP server automatically on startup.

---

How to use it

Once the app loads, just type in the chat box. Some examples:

Add ₹450 for groceries today
Show my expenses from last week
How much did I spend this month?
Summarise last month by category
Edit expense 5, change amount to 300
Delete expense 12
List all categories
Add a new category called freelance

The sidebar has a Show tool calls toggle. When turned on, you can see exactly which tools the model calls and what data comes back from the server — useful for understanding how MCP works under the hood.

---

How it works

You type a message
        ↓
client.py sends it to GPT-4o-mini with all tool schemas attached
        ↓
Model decides which tool to call (e.g. get_date_info → list_expenses)
        ↓
client.py calls the tool on the MCP server (main.py) via stdio
        ↓
main.py runs the tool, queries SQLite, returns JSON
        ↓
Model reads the result and writes a final reply
        ↓
client.py shows you the answer

The model may call multiple tools in sequence for one question. For example, "show last week's expenses" triggers two tool calls: get_date_info('last_week') first to get the correct dates, then list_expenses(start, end) with those dates.

---

Categories

Categories and subcategories are stored in categories.json. The file ships with 20 pre-built categories including food, transport, housing, health, entertainment, investments, and more.

You can edit this file directly, or use the chat to add, rename, or delete categories at any time. Changes take effect immediately without restarting the server.

---

Connecting to Claude Desktop

If you want to use this server directly inside Claude Desktop instead of the Streamlit interface:

1. Find your claude_desktop_config.json file:

   • Standard install: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json
   • Microsoft Store install: C:\Users\YourName\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

2. Add the following to the file:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "C:\\Users\\YourName\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "D:\\Projects\\expense-tracker-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

3. Fully restart Claude Desktop (use Task Manager to end the process, then reopen).

Note: If you installed Claude from the Microsoft Store, it may overwrite the config on each launch. In that case, use the Streamlit interface instead.

---

MCP Inspector (optional)

The MCP Inspector is a browser-based tool for testing your server's tools directly without the chat interface. It requires Node.js.

# Install Node.js from https://nodejs.org (LTS version)
# Then run:
uv run fastmcp dev inspector main.py

You can also use the hosted version without installing Node.js: inspector.modelcontextprotocol.io

---

Common issues

App shows "Failed to connect to MCP server"

• Check that UV_PATH in your .env points to the correct uv executable
• Check that MCP_SERVER_PATH points to the folder containing main.py
• Run uv run main.py manually in your terminal to see if there are any errors in the server itself

"Unknown category" error when adding an expense

• Type "list categories" in the chat to see all valid options
• Category and subcategory names are case-sensitive and must match exactly

expenses.db not found

• The database is created automatically the first time the server starts. If it is missing, just run the server once and it will be created.

---

Dependencies

Package	Purpose
fastmcp	Build and run the MCP server
streamlit	Chat interface
langchain-openai	Connect to GPT-4o-mini
langchain-mcp-adapters	Connect LangChain to MCP servers
python-dotenv	Load .env variables

---

.gitignore

Make sure your .gitignore includes the following so you do not accidentally commit sensitive files:

.env
expenses.db
.venv/
__pycache__/
*.pyc