Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking personal expenses with SQLite database storage. This server integrates with Claude Desktop to provide expense management capabilities through natural language.

Features

• ✅ Add, update, and delete expenses
• ✅ List expenses by date range
• ✅ Summarize expenses by category
• ✅ Flexible deletion by multiple criteria
• ✅ Predefined expense categories
• ✅ SQLite database for persistent storage

Prerequisites

• Python 3.10 or higher
• uv package manager
• Claude Desktop app

Installation

1. Install uv

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Initialize Project

# Create and navigate to project directory
mkdir expense-tracker-mcp-server
cd expense-tracker-mcp-server

# Initialize uv project
uv init .

3. Install Dependencies

# Install required packages
uv add fastmcp
uv add sqlite3  # Usually comes with Python

4. Create the Server

Create a file named main.py and paste the expense tracker code (from the document provided).

5. Test the Server

# Run the server
uv run main.py

Configuration

Claude Desktop Setup

1. Open Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the MCP server configuration:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YOUR_USERNAME/Desktop/expense-tracker-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

Important: Replace C:/Users/YOUR_USERNAME/Desktop/expense-tracker-mcp-server with your actual project path.

3. Restart Claude Desktop

Usage

Once configured, you can interact with the expense tracker through Claude using natural language:

Add Expense

"Add an expense: $50 for groceries on 2024-12-14"
"Log $25.50 spent on transport today with note 'Uber to office'"

List Expenses

"Show me all expenses from December 1 to December 14, 2024"
"List my expenses for last week"

Update Expense

"Update expense ID 5 to $75"
"Change the category of expense 3 to 'entertainment'"

Delete Expense

"Delete expense with ID 5"
"Remove all food expenses from last week"
"Delete expenses in the transport category"

Summarize Expenses

"Summarize my expenses by category for December 2024"
"What's my total spending on food this month?"

View Categories

"What expense categories are available?"
"Show me the list of categories"

Available Tools

add_expense

Add a new expense to the tracker.

Parameters:

• date (string): Date in YYYY-MM-DD format
• amount (float): Expense amount
• category (string): Expense category
• subcategory (string, optional): Subcategory
• note (string, optional): Additional notes

list_expenses

List all expenses within a date range.

Parameters:

• start_date (string): Start date (YYYY-MM-DD)
• end_date (string): End date (YYYY-MM-DD)

update

Update an existing expense (only provided fields will be updated).

Parameters:

• cid (int): Expense ID to update
• date (string, optional): New date
• amount (float, optional): New amount
• category (string, optional): New category
• subcategory (string, optional): New subcategory
• note (string, optional): New note

delete

Delete expenses based on various criteria.

Parameters:

• id (int, optional): Delete by ID
• date (string, optional): Delete by date
• category (string, optional): Delete by category
• subcategory (string, optional): Delete by subcategory
• amount (float, optional): Delete by amount
• note (string, optional): Delete by note
• start_date & end_date (strings, optional): Delete by date range

summarize

Get expense summaries grouped by category.

Parameters:

• start_date (string): Start date (YYYY-MM-DD)
• end_date (string): End date (YYYY-MM-DD)
• category (string, optional): Filter by specific category

Available Resources

expense://categories

Returns the list of available expense categories in JSON format.

Database Schema

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT ''
);

File Structure

expense-tracker-mcp-server/
├── main.py              # MCP server code
├── expense.db           # SQLite database (auto-created)
├── categories.json      # Categories list (auto-created)
├── pyproject.toml       # uv project configuration
└── README.md            # This file

Default Categories

The server comes with these default categories:

• food
• transport
• entertainment
• utilities
• healthcare

You can modify categories.json to add or remove categories.

Troubleshooting

Server not appearing in Claude Desktop

1. Check the configuration file path is correct
2. Ensure the command path points to your project directory
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

Database errors

If you encounter database errors:

# Delete the database to reset
rm expense.db

# Restart the server to recreate the database
uv run main.py

Import errors

# Reinstall dependencies
uv sync

Development

To modify the server:

1. Edit main.py
2. Test changes: uv run main.py
3. Restart Claude Desktop to load changes

Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

Support

For issues related to:

• MCP Protocol: MCP Documentation
• FastMCP: FastMCP GitHub
• Claude Desktop: Anthropic Support