DaniManas/exp-tracker-mcp-remote

Expense Tracker MCP Server

A powerful Remote Model Context Protocol (MCP) Server for tracking expenses, managing budgets, and analyzing spending patterns. Built with FastMCP and deployed on FastMCP Cloud.

Features

Core Expense Management

• Add Expenses - Record expenses with date, amount, category, subcategory, and notes
• List Expenses - View expenses within any date range
• Update Expenses - Modify existing expense entries
• Delete Expenses - Remove unwanted expense records

Advanced Analytics

• Summarize by Category - Get total spending per category for any time period
• Spending Statistics - View detailed stats (total, average, min, max, count)
• Spending Trends - Analyze trends by day, week, month, or year
• CSV Export - Export expense data to CSV files

Budget Management

• Set Budgets - Define spending limits for categories
• Budget Monitoring - Check budget status, see remaining amounts and percentage used
• Over-Budget Alerts - Get notified when spending exceeds budgets

Resources

• Expense Categories - Access predefined expense categories and subcategories via expense://categories

Architecture

Why Remote MCP Server?

This project is deployed as a remote MCP server on FastMCP Cloud, allowing:

• Network Accessibility - Access from any client over HTTP
• Centralized Data - Single source of truth for all your expenses
• Scalability - Handle multiple concurrent clients
• Cloud Deployment - No local installation required for clients

Why Asynchronous?

We migrated from synchronous to asynchronous programming using aiosqlite for several critical reasons:

1. Non-Blocking Operations

   • Database queries don't block the server
   • Multiple clients can make requests simultaneously
   • Improved responsiveness and throughput

2. Better Performance

   • Handle concurrent requests efficiently
   • Reduced latency for I/O operations
   • Optimal resource utilization

3. FastMCP Requirements

   • FastMCP's HTTP transport is built on async frameworks (Uvicorn/FastAPI)
   • Async tools integrate seamlessly with the event loop
   • Better compatibility with modern Python async ecosystem

4. Scalability

   • Single server instance can handle many clients
   • Graceful handling of slow database operations
   • Future-proof for adding more async operations

Quick Start

Prerequisites

• Python 3.8 or higher
• uv package manager (recommended) or pip

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd test-remote-server
   

2. Install dependencies

   Using uv (recommended):

   uv pip install fastmcp aiosqlite
   

   Or using pip:

   pip install fastmcp aiosqlite
   

Running Locally

Start the server:

uv run --with fastmcp --with aiosqlite python main.py

Or with Python directly:

python main.py

The server will start on http://0.0.0.0:8888/mcp

Cloud Deployment

This server is deployed on FastMCP Cloud and connected via GitHub:

Deployment Steps

1. Push to GitHub

   git add .
   git commit -m "Deploy expense tracker"
   git push origin main
   

2. Connect on FastMCP Cloud

   • Visit fastmcp.cloud
   • Connect your GitHub repository
   • FastMCP Cloud will automatically deploy your server

3. Access Your Server

   • You'll receive a unique URL for your deployed server
   • Use this URL to connect from any MCP client

Available Tools

1. add_expense

Add a new expense entry.

Parameters:

• date (string, required) - Date in YYYY-MM-DD format
• amount (float, required) - Expense amount
• category (string, required) - Expense category
• subcategory (string, optional) - Subcategory
• note (string, optional) - Additional notes

Example:

{
  "date": "2025-10-11",
  "amount": 45.50,
  "category": "Food & Dining",
  "subcategory": "Restaurants",
  "note": "Lunch with team"
}

2. list_expenses

List expenses within a date range.

Parameters:

• start_date (string, required) - Start date (YYYY-MM-DD)
• end_date (string, required) - End date (YYYY-MM-DD)

3. update_expense

Update an existing expense.

Parameters:

• id (integer, required) - Expense ID
• 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

4. delete_expense

Delete an expense by ID.

Parameters:

• id (integer, required) - Expense ID to delete

5. summarize

Get spending summary by category.

Parameters:

• start_date (string, required) - Start date
• end_date (string, required) - End date
• category (string, optional) - Filter by specific category

Returns: List of categories with total amounts

6. get_statistics

Get detailed spending statistics.

Parameters:

• start_date (string, required) - Start date
• end_date (string, required) - End date
• category (string, optional) - Filter by category

Returns:

{
  "count": 25,
  "total": 1250.75,
  "average": 50.03,
  "min": 5.99,
  "max": 250.00
}

7. get_spending_trends

Analyze spending trends over time.

Parameters:

• start_date (string, required) - Start date
• end_date (string, required) - End date
• group_by (string, optional) - "day", "week", "month", or "year" (default: "month")
• category (string, optional) - Filter by category

Returns: Time-series data with transaction counts and amounts

8. export_to_csv

Export expenses to a CSV file.

Parameters:

• start_date (string, required) - Start date
• end_date (string, required) - End date
• file_path (string, required) - Output file path

9. set_budget

Set a budget limit for a category.

Parameters:

• category (string, required) - Category name
• amount (float, required) - Budget amount
• start_date (string, required) - Budget start date
• end_date (string, required) - Budget end date

10. check_budget_status

Check budget status for a category.

Parameters:

• category (string, required) - Category name
• start_date (string, required) - Period start date
• end_date (string, required) - Period end date

Returns:

{
  "status": "ok",
  "category": "Food & Dining",
  "budget_amount": 500.00,
  "actual_spending": 425.50,
  "remaining": 74.50,
  "percentage_used": 85.10,
  "is_over_budget": false
}

Project Structure

test-remote-server/
├── main.py              # Main server application
├── categories.json      # Expense categories and subcategories
├── README.md           # This file
└── expenses.db         # SQLite database (created automatically)

Database Schema

expenses Table

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

budgets Table

CREATE TABLE budgets (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category TEXT NOT NULL,
    amount REAL NOT NULL,
    start_date TEXT NOT NULL,
    end_date TEXT NOT NULL,
    UNIQUE(category, start_date, end_date)
)

Expense Categories

The server includes 11 predefined categories accessible via the expense://categories resource:

1. Food & Dining - Groceries, Restaurants, Coffee & Tea, Fast Food, Snacks
2. Transportation - Gas & Fuel, Public Transit, Taxi & Rideshare, Parking, Car Maintenance
3. Shopping - Clothing, Electronics, Home & Garden, Books, Gifts
4. Entertainment - Movies & Shows, Music, Games, Sports, Hobbies
5. Bills & Utilities - Electricity, Water, Internet, Phone, Gas
6. Healthcare - Doctor, Pharmacy, Insurance, Dental, Fitness
7. Education - Tuition, Books & Supplies, Courses, Software, Training
8. Personal - Haircut, Spa & Beauty, Personal Care, Subscriptions, Memberships
9. Travel - Flights, Hotels, Rental Cars, Activities, Food
10. Housing - Rent, Mortgage, Home Insurance, Repairs, Furniture
11. Other - Miscellaneous, Cash, Fees, Taxes, Charity

Configuration

The server uses the following default configuration:

• Host: 0.0.0.0 (accessible from any network interface)
• Port: 8888
• Transport: HTTP (Streamable)
• Database: SQLite stored in system temp directory (/tmp/expenses.db)

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests

License

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

Links

• FastMCP Documentation
• FastMCP Cloud
• Model Context Protocol

Use Cases

• Personal Finance Management - Track daily expenses and stay within budget
• Small Business Accounting - Monitor business expenses by category
• Family Budget Planning - Shared expense tracking for households
• Financial Analysis - Analyze spending patterns and trends
• Budget Compliance - Ensure spending stays within defined limits

Support

If you encounter any issues or have questions:

1. Check the FastMCP documentation
2. Review the error messages in the server logs
3. Open an issue on GitHub

Made with using FastMCP | Deployed on FastMCP Cloud