Expense Tracker MCP
A powerful Model Context Protocol (MCP) server for expense tracking that integrates seamlessly with Claude Desktop. Built with FastMCP, this server enables you to manage your personal or business expenses through natural conversations with Claude AI.
🎯 What is This Project?
This is an expense tracking system that uses the Model Context Protocol to expose expense management capabilities to AI assistants like Claude. Instead of using a traditional UI, you can interact with your expense data through natural language conversations.
Key Features
- 💰 Add Expenses: Track expenses with date, amount, category, subcategory, and notes
- 📊 List Expenses: View expenses within any date range
- 📈 Summarize Expenses: Get category-wise summaries and totals for any period
- 🏷️ Categories: Access predefined expense categories for consistent tracking
- 💾 SQLite Database: All data stored locally in a lightweight database
- 🤖 AI Integration: Talk to Claude Desktop to manage your expenses naturally
How It Works
The server exposes MCP tools that Claude can call on your behalf:
add_expense(date, amount, category, subcategory, note)- Add new expense entrieslist_expenses(start_date, end_date)- Retrieve expenses within a date rangesummarize(start_date, end_date, category)- Get expense summaries by categorycategoriesresource - View available expense categories
Example conversation with Claude:
- "Add an expense of $45.50 for groceries on October 15th"
- "Show me all my expenses from October 1st to October 15th"
- "How much did I spend on food this month?"
- "Summarize my expenses by category for the last week"
📦 Installation & Setup
1. Install uv
First, install the uv package manager. Visit uv documentation for installation instructions.
2. Create a Project Folder
Create a new directory for your project:```bash
mkdir expense-tracker-mcp
cd expense-tracker-mcp
### 3. Initialize the Project
Open the folder in your terminal and run:```bash
uv init .
4. Install Dependencies
Add FastMCP to your project:```bash
uv add fastmcp
## Usage
### Check Version
To verify the FastMCP installation (make sure you're in the virtual environment):```bash
fastmcp version
Test the Server
Run the server in development mode:```bash
uv run fastmcp dev main.py
### Run the Server
Run the server in production mode:```bash
uv run fastmcp run main.py
🚀 Getting Started with Claude Desktop
Once installed, you can interact with your expenses through Claude Desktop using natural language. Here's what you can do:
Example Commands
Adding expenses:
- "Add a $50 expense for groceries today"
- "Record a $120 expense for electricity bill on October 10th with note 'monthly utility'"
Viewing expenses:
- "Show me all expenses from October 1st to October 15th"
- "List my expenses for this week"
Analyzing spending:
- "Summarize my expenses by category for this month"
- "How much did I spend on transportation last week?"
- "What are my total expenses for October?"
Managing categories:
- "Show me the available expense categories"
- "What subcategories are under Food?"
Adding to Claude Desktop
Install to Claude Desktop
Run the following command to add the server to Claude Desktop:```bash
uv run fastmcp install claude-desktop main.py
**⚠️ Important:** This command may give an error because the generated config file will contain just `"uv"` instead of the absolute path to the `uv` executable.
### Fix the Configuration
You need to manually update the Claude Desktop config file and replace `"uv"` with the absolute path to your `uv` executable.
**Example path (Windows):**```
"C:\\Users\\jiten\\AppData\\Roaming\\Python\\Python313\\Scripts\\uv.exe"
Finding your uv path:
- Windows: Run where uv in PowerShell or Command Prompt
- macOS/Linux: Run which uv in the terminal
Converting FastAPI to FastMCP
If you have an existing FastAPI application, converting it to FastMCP is straightforward:```python
from fastmcp import FastMCP
from main import app # Import your FastAPI app
mcp = FastMCP.from_fastapi(
name="XYZ",
app=app,
)
if name == "main":
print("Running MCP")
mcp.run()
## 📁 Project Structure```
expense-tracker-mcp/
├── main.py # Main MCP server file with tools and resources
├── categories.json # Predefined expense categories and subcategories
├── expenses.db # SQLite database storing all expense records
├── pyproject.toml # Project dependencies and metadata
├── uv.lock # Lock file for reproducible dependency installation
└── README.md # This documentation file
Database Schema
The expenses table structure:
| Column | Type | Description |
|---|---|---|
id |
INTEGER | Primary key (auto-increment) |
date |
TEXT | Expense date (YYYY-MM-DD format) |
amount |
REAL | Expense amount |
category |
TEXT | Main category (e.g., Food, Transport) |
subcategory |
TEXT | Optional subcategory |
note |
TEXT | Optional note or description |
License
MIT
