Expense Tracker MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to manage your personal expenses through natural conversation. Built with Python using fastmcp and uv.

Features

Add Expenses: Record expenses with amount, category, date, and description
List & Filter: View expenses by category and date range
Summarize: Get spending summaries grouped by category
Update Expenses: Modify existing expense records
Delete Expenses: Remove unwanted expense entries
Natural Language Interface: Interact with your expense data conversationally through Claude

Prerequisites

Python 3.10 or higher
uv package manager

Installation

# Clone the repository
git clone https://github.com/Khushi-c-sharma/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

Configuration

Add the server to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/expense-tracker-mcp",
        "run",
        "expense-tracker"
      ]
    }
  }
}

Usage Examples

Once configured, you can interact with your expenses through Claude naturally:

You: "Add expense 2632 spent yesterday for shopping dress for my convocation"
Claude: *Adds the expense with proper categorization*

You: "Show me all my expenses this month"
Claude: *Lists and summarizes your monthly expenses*

You: "How much did I spend on food in September?"
Claude: *Provides category-specific spending summary*

Available Tools

`add_expense`

Add a new expense to the database.

Parameters: amount (required), category (required), date, description, subcategory

`list_expenses`

List expenses filtered by category and optional date range.

Parameters: category, start_date, end_date

`summarize`

Get total expenses by category within a date range.

Parameters: start_date (required), end_date (required), category

`update_expense`

Update an existing expense.

Parameters: expense_id (required), amount, category, date, description, subcategory

`delete_expense`

Delete an expense by ID.

Parameters: expense_id (required)

Database

Expenses are stored in a local SQLite database (expenses.db) with the following schema:

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

Development

# Run the server directly
uv run expense-tracker

# Run in development mode with auto-reload
uv run python src/expense_tracker/server.py

# Install new dependencies
uv add package-name

# Update dependencies
uv sync

Project Structure

expense-tracker-mcp/
├── main.py                     # Main MCP server code
├── pyproject.toml              # Project configuration
├── uv.lock                     # Locked dependencies
├── expenses.db                 # SQLite database (created on first run)
└── README.md

Use Cases

Personal Finance Tracking: Monitor daily spending habits
Budget Management: Track expenses by category to stay within budget
Expense Reports: Generate summaries for tax purposes or reimbursements
Shopping Tracking: Keep records of purchases and major expenses
Financial Analysis: Analyze spending patterns over time

Built With

fastmcp - Fast, Pythonic MCP server framework
uv - Fast Python package installer and resolver
SQLite - Lightweight database for expense storage
Model Context Protocol - Protocol for AI-application integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Server not appearing in Claude Desktop?

Ensure the path in claude_desktop_config.json is absolute and correct
Restart Claude Desktop after configuration changes
Check Claude Desktop logs for error messages

Database errors?

Ensure the directory is writable
Delete expenses.db to recreate the database from scratch

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ for better expense tracking through AI