Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking and managing expenses. This server enables AI assistants to help you manage your finances through natural language interactions.

Overview

The Expense MCP Server implements the Model Context Protocol to provide expense tracking capabilities to AI tools like Claude Desktop, Cursor, and other MCP-compatible clients. Track expenses, categorize spending, and get insights into your financial habits through conversational AI.

Features

• Add Expenses: Record expenses with categories, amounts, and descriptions
• View Expenses: Retrieve and filter expenses by date, category, or amount
• Expense Summaries: Get spending summaries and financial insights
• Member Management: Track expenses for multiple members or groups
• Persistent Storage: All data is stored locally in JSON format

Prerequisites

• Python 3.10 or higher
• uv (Python package manager)

Installation

1. Install uv

If you haven't already installed uv:

macOS/Linux:

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

Windows:

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

2. Clone the Repository

git clone https://github.com/shivamprasad1001/expense-mcp-server.git
cd expense-mcp-server

3. Install Dependencies

uv sync

Finding Your uv Path

To avoid configuration errors, you'll need the absolute path to your uv executable.

macOS/Linux:

which uv

Windows (PowerShell):

where.exe uv

The command will output something like:

• macOS: /Users/yourusername/.local/bin/uv or /opt/homebrew/bin/uv
• Linux: /home/yourusername/.local/bin/uv
• Windows: C:\Users\YourUsername\.local\bin\uv.exe

Configuration

For Claude Desktop

Add this configuration to your Claude Desktop config file:

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

{
  "mcpServers": {
    "expense-tracker": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/expense-mcp-server",
        "run",
        "expense-mcp-server"
      ]
    }
  }
}

Example (macOS):

{
  "mcpServers": {
    "expense-tracker": {
      "command": "/Users/johndoe/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/johndoe/projects/expense-mcp-server",
        "run",
        "expense-mcp-server"
      ]
    }
  }
}

Example (Windows):

{
  "mcpServers": {
    "expense-tracker": {
      "command": "C:\\Users\\JohnDoe\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\Users\\JohnDoe\\projects\\expense-mcp-server",
        "run",
        "expense-mcp-server"
      ]
    }
  }
}

For Cursor

Add this to your Cursor MCP configuration at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/expense-mcp-server",
        "run",
        "expense-mcp-server"
      ]
    }
  }
}

For Other MCP Clients

Refer to your MCP client's documentation for configuration. Generally, you'll need to specify:

• Command: Absolute path to uv (e.g., /Users/username/.local/bin/uv)
• Args: ["--directory", "/absolute/path/to/expense-mcp-server", "run", "expense-mcp-server"]

Usage

Once configured, restart your AI assistant (Claude Desktop/Cursor) to load the MCP server. You can then interact with the expense tracker through natural language:

Example Interactions

• "Add a $50 expense for groceries"
• "Show me all my expenses this month"
• "How much did I spend on restaurants?"
• "What's my total spending this week?"
• "Add a $25 expense for transportation"
• "List all expenses over $100"
• "Add a new member named John"
• "Show me all members and their expenses"

Available Tools

The MCP server exposes the following tools for AI assistants:

• add_expense: Record a new expense with amount, category, and description
• list_expenses: View all expenses or filter by criteria (date, category, amount)
• get_summary: Get spending summaries, totals, and statistics
• add_member: Add a new member for expense tracking
• list_members: View all members
• delete_expense: Remove an expense by ID
• update_expense: Modify an existing expense

Data Storage

All expense data is stored locally in members.json in the project directory. This file contains:

• Member information
• Expense records with timestamps
• Categories and metadata

Data Privacy: All your data stays on your local machine. Nothing is sent to external servers.

Development

Project Structure

expense-mcp-server/
├── main.py              # Main MCP server implementation
├── members.json         # Data storage (created on first run)
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
└── README.md           # This file

Running in Development Mode

# Navigate to project directory
cd expense-mcp-server

# Run the server
uv run expense-mcp-server

Testing with MCP Inspector

You can test the MCP server using the MCP Inspector tool:

npx @modelcontextprotocol/inspector uv --directory /path/to/expense-mcp-server run expense-mcp-server

The inspector provides a web interface to test all available tools and resources.

Troubleshooting

Common Issues

"command not found: uv"

• Make sure you've installed uv and it's in your PATH
• Use the absolute path to uv in your configuration (see "Finding Your uv Path" section)

"No module named 'mcp'"

• Run uv sync in the project directory to install dependencies

Changes not reflecting in Claude Desktop

• Restart Claude Desktop completely after configuration changes
• Check the Developer Tools in Claude Desktop (View > Developer Tools) for errors

Server not starting

• Verify all paths in the configuration are absolute paths
• Ensure the members.json file is writable
• Check Python version with python --version (must be 3.10+)

Contributing

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

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

Roadmap

• [ ] Add budget tracking and alerts
• [ ] Export expenses to CSV/Excel
• [ ] Support for multiple currencies
• [ ] Recurring expense tracking
• [ ] Category-based analytics and charts
• [ ] Receipt image storage (with OCR)

License

This project is open source and available under the MIT License.

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the Model Context Protocol documentation
• Join the MCP community discussions

About MCP

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). Think of MCP like a USB-C port for AI - it provides a standardized way to connect AI models to different data sources and tools.

Learn more at modelcontextprotocol.io.

Author

Created by shivamprasad1001

---

Important: Always use absolute paths in your MCP configuration to avoid "command not found" errors. Replace placeholder paths with your actual system paths.