Money-Tracker-MCP by JAI0705 - MCP Server

<<<<<<< HEAD

Expense Tracker MCP Server

An MCP (Model Context Protocol) server for tracking personal expenses. This server provides tools to add and list expenses, storing them in a local SQLite database. It's designed to work seamlessly with Cursor IDE and other MCP-compatible clients.

📋 Table of Contents

✨ Features

Add Expenses: Record expenses with date, amount, category, subcategory, and optional notes
List Expenses: Retrieve all stored expenses from the database
SQLite Database: Local, lightweight database storage (no external database required)
MCP Integration: Works with Cursor IDE and other MCP-compatible clients
FastMCP Framework: Built on FastMCP for reliable MCP server functionality

📦 Requirements

Python 3.13 or higher
pip (Python package manager)

🚀 Installation

Clone or navigate to the project directory:

cd "/home/jai/Desktop/Coding_Hub/Expense tracker MCP"

Install the project and its dependencies:
```
pip install -e .
```
This will install:
- fastmcp (MCP server framework)
- All required transitive dependencies
Verify installation:
```
python main.py --help
```
You should see the FastMCP banner and server information.

🔧 Setup for Cursor IDE

To use this MCP server with Cursor IDE:

Create or edit the Cursor MCP configuration file:

Location: ~/.cursor/mcp.json

Add the following configuration:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "python",
      "args": ["/home/jai/Desktop/Coding_Hub/Expense tracker MCP/main.py"],
      "env": {}
    }
  }
}

Note: Update the path in args to match your actual project location.

Restart Cursor:
- Close Cursor completely
- Reopen Cursor
- The MCP server should now be available
Verify Connection:
- Check if "expense-tracker" appears in Cursor's MCP server list
- Look for MCP tools in the available tools section

💡 Usage

Once set up, you can interact with the expense tracker through natural language commands in Cursor:

Example Commands:

Add an expense:
- "Add a $25.50 expense for groceries today"
- "Record a $100 expense for rent on 2024-01-15 in the housing category"
- "Add $15.99 for lunch at restaurant, category: food, subcategory: dining out"
List expenses:
- "Show me all my expenses"
- "List all expenses from the database"
- "What expenses do I have?"

🛠️ Available Tools

The server provides two main MCP tools:

1. `add_expense`

Adds a new expense entry to the database.

Parameters:

date (str, required): Date of the expense (format: YYYY-MM-DD)
amount (float, required): Expense amount
category (str, required): Expense category (e.g., "food", "transport", "housing")
subcategory (str, optional): More specific category (e.g., "groceries", "restaurant")
note (str, optional): Additional notes about the expense

Returns:

{
  "status": "ok",
  "id": 1
}

Example:

add_expense(
    date="2024-01-15",
    amount=25.50,
    category="food",
    subcategory="groceries",
    note="Weekly shopping"
)

2. `list_expenses`

Retrieves all expenses from the database.

Parameters: None

Returns:

[
  {
    "id": 1,
    "date": "2024-01-15",
    "amount": 25.50,
    "category": "food",
    "subcategory": "groceries",
    "note": "Weekly shopping"
  },
  ...
]

📁 Project Structure

Expense tracker MCP/
├── main.py                    # Main MCP server implementation
├── pyproject.toml            # Project configuration and dependencies
├── expense.db                # SQLite database (created automatically)
├── README.md                 # This file
├── MCP_Setup_Instructions.txt # Detailed setup instructions
└── expense_tracker_mcp.egg-info/  # Package metadata

🗄️ Database Schema

The SQLite database uses 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 DEFAULT '',
    note TEXT DEFAULT ''
)

Fields:

id: Auto-incrementing unique identifier
date: Date of the expense (stored as TEXT)
amount: Expense amount (REAL/FLOAT)
category: Main expense category (required)
subcategory: Optional subcategory
note: Optional additional notes

🔍 Technical Details

Framework: FastMCP 2.12.4
Transport: STDIO (Standard Input/Output)
Database: SQLite (local file: expense.db)
Python Version: 3.13+
Server Name: "Expense Tracker"
Protocol: MCP (Model Context Protocol)

The server runs as a subprocess of the MCP client (like Cursor) and communicates via STDIO using the MCP protocol.

🐛 Troubleshooting

Server doesn't appear in Cursor

Check the configuration path:
- Verify the path in ~/.cursor/mcp.json is correct
- Ensure it points to the actual location of main.py
Verify Python installation:
```
python --version
```
Should show Python 3.13 or higher
Reinstall dependencies:
```
pip install -e .
```
Test the server manually:
```
python main.py --help
```
Should display the FastMCP banner without errors
Check Cursor logs:
- Look for error messages in Cursor's developer console or logs
- Common issues: path errors, missing dependencies, Python version mismatch

Database Issues

The database file (expense.db) is created automatically on first use
If you need to reset the database, simply delete expense.db and restart the server
The database is stored in the same directory as main.py

Permission Errors

Ensure you have read/write permissions in the project directory
The database file needs write permissions

📝 Notes

The database is stored locally in the project directory
All expenses persist between sessions
The server initializes the database automatically on startup
Date format should be YYYY-MM-DD (e.g., "2024-01-15")

🔄 Future Enhancements

Potential features for future versions:

Filter expenses by date range
Filter expenses by category
Calculate totals and statistics
Export expenses to CSV/JSON
Delete or update existing expenses
Budget tracking and alerts

📄 License

This project is provided as-is for personal use.

For detailed setup instructions, see MCP_Setup_Instructions.txt.

=======

MCP Server for Money Tracking.

f0df9ea44fc4e8adac20e6f2cf40efee30b8132e