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
✅ Local and remote deployment options

Quick Start Options

Choose the setup method that works best for you:

Option 1: Direct Remote Server (Instant Setup - Claude Pro Only)

⚠️ Requires Claude Pro subscription - Direct URL connections are a Pro feature.

Connect directly to the deployed remote server without any local setup:

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
Add this configuration:

{
  "mcpServers": {
    "expense-tracker": {
      "url": "https://boiling-aqua-trout.fastmcp.app/mcp"
    }
  }
}

Restart Claude Desktop
Start tracking expenses immediately! 🎉

Note: This remote server is hosted on FastMCP Cloud. Your data is stored on the remote server.

Don't have Claude Pro? Use Option 2 below to connect via a local proxy server!

Option 2: Local Proxy to Remote Server (For Free Users & Customization)

✅ Works with Claude Free plan! Run a local MCP server that proxies requests to the remote server. This is the way to access remote MCP servers if you don't have Claude Pro.

Use cases:

Connect to remote servers on Claude Free plan
Add custom logging or middleware
Run locally while using remote data
Extend functionality with additional features

Setup Steps:

Install uv (if not already installed):

Windows (PowerShell):

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

macOS/Linux:

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

Create a new project:

mkdir expense-tracker-proxy
cd expense-tracker-proxy
uv init .

Install FastMCP:

uv add fastmcp

Create proxy server (main.py):

from fastmcp import FastMCP

mcp = FastMCP.as_proxy(
    "https://boiling-aqua-trout.fastmcp.app/mcp",
    name="expense tracker remote proxy server"
)

if __name__ == "__main__":
    mcp.run()

Configure Claude Desktop:

{
  "mcpServers": {
    "expense-tracker-proxy": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YOUR_USERNAME/path/to/expense-tracker-proxy",
        "run",
        "main.py"
      ]
    }
  }
}

Important: Replace the path with your actual project directory.

Restart Claude Desktop

Benefits of Proxy Approach:

Add custom logging or middleware
Modify requests/responses before forwarding
Run locally but leverage remote infrastructure
Easy to extend with additional features

Option 3: Full Local Installation (Complete Control & Privacy)

For those who want full control, privacy, and the ability to modify the core server logic.

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. Clone or Create Project

# Clone this repository
git clone https://github.com/Sudhanvaha/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

# OR create from scratch
mkdir expense-tracker-mcp-server
cd expense-tracker-mcp-server
uv init .

3. Install Dependencies

# Install required packages
uv add fastmcp

4. Create the Server

Copy the full main.py code from this repository into your project.

5. Test the Server

# Run the server
uv run main.py

6. Configure Claude Desktop for Local Server

Open Claude Desktop configuration file (locations mentioned above)
Add the MCP server configuration:

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

Important: Replace the path with your actual project directory path.

Restart Claude Desktop

Usage

Once configured (via any method), 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_expense`

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_expense`

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_expenses`

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

For Full Local Installation:

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

For Proxy Setup:

expense-tracker-proxy/
├── main.py              # Proxy server code (5 lines!)
└── pyproject.toml       # uv project configuration

Default Categories

The server comes with these default categories:

food
transport
entertainment
utilities
healthcare

You can modify categories.json to add or remove categories (local installation only).

Deployment Options Comparison

Feature	Direct Remote (Pro)	Local Proxy (Free/Pro)	Full Local
Claude Plan	Pro only	Free & Pro	Free & Pro
Setup Time	2 minutes	5 minutes	15-20 minutes
Privacy	Remote storage	Remote storage	Complete privacy
Customization	None	Middleware only	Full control
Maintenance	Zero	Minimal	Manual updates
Internet Required	Yes	Yes	No
Code Required	No	5 lines	Full codebase
Cost	Pro subscription	Free	Free

Troubleshooting

Server not appearing in Claude Desktop

Check the configuration file path is correct
Ensure the command path points to your project directory (for local/proxy setup)
Verify the remote URL is correct (for direct remote setup)
Restart Claude Desktop completely
Check Claude Desktop logs for errors

Remote Server Issues

If the remote server isn't responding:

Check your internet connection
Verify the URL: https://boiling-aqua-trout.fastmcp.app/mcp
Try removing and re-adding the configuration
Contact me via GitHub issues if the problem persists

Proxy Server Issues

If the proxy isn't working:

Test the proxy server independently: uv run main.py
Check if the remote URL is accessible
Verify your FastMCP installation: uv add fastmcp
Check Claude Desktop configuration paths

Database errors (Local Installation Only)

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

Extending the Proxy Server

You can add custom logic to the proxy server:

from fastmcp import FastMCP

mcp = FastMCP.as_proxy(
    "https://boiling-aqua-trout.fastmcp.app/mcp",
    name="expense tracker remote proxy server"
)

# Add custom logging
@mcp.tool()
def log_expense_activity():
    """Log all expense activities"""
    # Your custom logging logic here
    pass

if __name__ == "__main__":
    mcp.run()

Modifying the Full Server

To modify the server:

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

Deploying Your Own Remote Server

Want to deploy your own version on FastMCP Cloud?

Sign up at FastMCP Cloud
Follow their deployment instructions
Update the URL in your Claude Desktop configuration or proxy code
Share your server URL with others!

Contributing

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

Roadmap

Add budget tracking and alerts
Support for multiple currencies
Recurring expense templates
Export to CSV/Excel
Data visualization and charts
Multi-user support with authentication
Authentication for remote server access

Support

For issues related to:

This Project: GitHub Issues
MCP Protocol: MCP Documentation
FastMCP: FastMCP GitHub
Claude Desktop: Anthropic Support

Acknowledgments

Built with:

FastMCP - Framework for building MCP servers
Anthropic Claude - AI assistant platform
Model Context Protocol - Standard for AI-application integration

⭐ If you find this project helpful, please consider giving it a star on GitHub!

📧 Questions? Open an issue or reach out on LinkedIn