bhavuk1409/expense-tracker-mcp-server

MCP Expense Tracker Server

A Model Context Protocol (MCP) server for managing personal expenses with SQLite database storage. This server provides tools for adding, listing, and managing expense entries through any MCP-compatible client like Claude Desktop.

Features

• Add new expense entries
• List expenses within date ranges
• SQLite database for persistent storage
• Predefined expense categories
• Subcategory support
• Notes and descriptions
• MCP-compliant for seamless integration

Prerequisites

• Python 3.13 or higher
• uv package manager
• Claude Desktop (for testing) or any MCP-compatible client

Installation

1. Clone the repository:

   git clone <repository-url>
   cd mcp-expense-tracker-server
   

2. Install dependencies:

   uv sync
   

3. Verify installation:

   uv run python main.py
   

Usage

Running the Server

Development Mode (with FastMCP Inspector)

uv run fastmcp dev main.py

This starts the server with a web interface at http://127.0.0.1:6274 for testing.

Production Mode

uv run fastmcp run main.py

Integration with Claude Desktop

uv run fastmcp install claude-desktop main.py

Available Tools

add_expense

Add a new expense entry to the database.

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

Example:

{
  "date": "2024-10-02",
  "amount": 25.50,
  "category": "Food & Dining",
  "subcategory": "groceries",
  "note": "Weekly grocery shopping"
}

list_expenses

List expense entries within a date range.

Parameters:

• start_date (string): Start date in YYYY-MM-DD format
• end_date (string): End date in YYYY-MM-DD format

Example:

{
  "start_date": "2024-10-01",
  "end_date": "2024-10-31"
}

get_categories

Retrieve all available expense categories and subcategories.

Returns: JSON object with category structure

Available Resources

expense://categories

Access the categories configuration as a JSON resource.

Database Schema

The SQLite database contains an expenses table with the following structure:

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 ''
);

Categories Configuration

The categories.json file contains predefined expense categories and subcategories:

{
  "food": ["groceries", "dining_out", "coffee_tea", ...],
  "transportation": ["gas", "public_transport", "taxi", ...],
  "entertainment": ["movies", "games", "books", ...],
  ...
}

You can modify this file to customize categories for your needs.

File Structure

mcp-expense-tracker-server/
├── main.py              # Main MCP server implementation
├── categories.json      # Expense categories configuration
├── expenses.db          # SQLite database (auto-created)
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
└── README.md           # This file

Development

Running Tests

# Test the server directly
uv run python main.py

# Test with FastMCP inspector
uv run fastmcp dev main.py

Adding New Features

1. New Tools: Add new @mcp.tool() decorated functions in main.py
2. New Resources: Add new @mcp.resource() decorated functions
3. Database Changes: Modify the init_db() function for schema updates

Debugging

Common Issues

1. "Connection Error - Did you add the proxy session token in Configuration?"

   • Make sure the server is running
   • Use the pre-filled URL with session token
   • Check that ports 6274 and 6277 are available

2. "ProgrammingError: Error binding parameter"

   • Ensure parameters are in correct format (not dictionaries)
   • Check data types match function signatures

3. "File not found: categories.json"

   • Ensure categories.json exists in the project directory
   • Run the server from the correct directory

Logs

The server logs are displayed in the terminal when running in development mode.

Integration with Claude Desktop

1. Install the server:

   uv run fastmcp install claude-desktop main.py
   

2. Restart Claude Desktop

3. Test the integration:

   • Ask Claude: "Add an expense for $15 lunch today"
   • Ask Claude: "Show me my expenses for this month"

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

[Add your license here]

Troubleshooting

Port Conflicts

If you get port conflicts, you can:

1. Kill existing processes: pkill -f fastmcp
2. Use different ports by modifying the FastMCP configuration

Database Issues

• Delete expenses.db to reset the database
• The database will be recreated automatically on next run

Permission Issues

Make sure you have write permissions in the project directory for database creation.

Examples

Sample Expense Entries

# Adding various expenses
add_expense("2024-10-02", 50.00, "groceries", "", "Weekly shopping")
add_expense("2024-10-02", 12.50, "transportation", "gas", "Gas station")
add_expense("2024-10-02", 8.75, "entertainment", "coffee", "Morning coffee")

Sample Queries

# List all October expenses
list_expenses("2024-10-01", "2024-10-31")

# List expenses for a specific week
list_expenses("2024-10-01", "2024-10-07")

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the FastMCP documentation
3. Open an issue in the repository

Built with FastMCP - A fast, simple framework for building MCP servers.

expense-tracker-mcp-server