expense-tracker-mcp-server by bhakti259 - MCP Server

Expense Tracker MCP Server

A powerful Model Context Protocol (MCP) server for tracking and managing personal expenses. This server integrates with Claude Desktop to provide seamless expense management through natural language interactions.

Features

🛠️ Tools

add_expense: Add new expenses with flexible date parsing (supports "today", "yesterday", "Nov 27, 2025", etc.)
list_expenses: List expenses with filtering by category, date range, and natural language date queries
summarize_expenses: Get expense summaries by category with totals and percentages
update_expense: Modify existing expense records
delete_expense: Remove expense records by ID

📋 Resources

expense://categories: Access predefined expense categories and subcategories from categories.json

✨ Key Capabilities

Natural Language Date Support: Use phrases like "last week", "last month", "this year", "last 30 days"
SQLite Database: Lightweight and efficient local storage
Category Management: Pre-defined categories with subcategories for better organization
Flexible Filtering: Filter expenses by date range, category, or specific criteria
Rich Summaries: View spending patterns with category-wise breakdowns and percentages

Installation

Prerequisites

Python 3.8 or higher
uv package manager (recommended)
Claude Desktop

Steps

Clone the repository

git clone <your-repo-url>
cd Expense-Tracker-MCP-Server

Install dependencies

Using uv (recommended):

uv pip install -r requirements.txt

Or using pip:

pip install -r requirements.txt

Install to Claude Desktop

uv run fastmcp install claude-desktop main.py

Or manually add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json on Mac/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "Expense Tracker Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/Expense-Tracker-MCP-Server/main.py"
      ]
    }
  }
}

Restart Claude Desktop

Completely quit and restart Claude Desktop to load the MCP server.

Usage

Once installed, you can interact with the Expense Tracker directly in Claude Desktop using natural language:

Adding Expenses

"Add an expense of $45.50 for groceries yesterday"
"I spent $20 on lunch today in the Food category"
"Add expense: $100, Transport, Fuel, Nov 25, 2025, note: Monthly fuel"

Listing Expenses

"Show me all expenses from last week"
"List my Food expenses from this month"
"Show expenses from last 30 days"

Summarizing Expenses

"Summarize my expenses for last month"
"Show category-wise breakdown for this year"
"Summarize Food expenses from last week"

Updating Expenses

"Update expense ID 5, change amount to $55.50"
"Change expense 3's category to Transport"

Deleting Expenses

"Delete expense with ID 7"

Database Schema

The server uses SQLite with the following schema:

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

Development

Running Locally

uv run fastmcp dev main.py

Project Structure

Expense-Tracker-MCP-Server/
├── main.py                 # Main MCP server code
├── categories.json         # Expense categories and subcategories
├── requirements.txt        # Python dependencies
├── pyproject.toml         # Project metadata
├── expenses.db            # SQLite database (auto-created)
└── README.md              # This file

Requirements

fastmcp>=2.0.0 - FastMCP framework for building MCP servers
python-dateutil>=2.8.0 - Flexible date parsing

Troubleshooting

Server not showing in Claude Desktop

Ensure Claude Desktop is completely quit (not just closed)
Check the config file has correct absolute paths
Verify the command path to uv is correct
Restart Claude Desktop

Database issues

The expenses.db file is created automatically in the project directory. If you encounter issues:

Delete expenses.db and restart the server
Check file permissions

Date parsing errors

The server supports various date formats. If you encounter parsing errors:

Use ISO format: "YYYY-MM-DD" (e.g., "2025-11-27")
Use common formats: "Nov 27, 2025", "27th November 2025"
Use relative dates: "today", "yesterday", "last week"

Contributing

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

License

MIT License - feel free to use this project for personal or commercial purposes.

Author

Created with FastMCP and Claude

Acknowledgments

Built with FastMCP
Powered by Model Context Protocol

bhakti259/expense-tracker-mcp-server