📘 Expense Tracker MCP Server

AI-powered budgeting, smart expense tracking, and affordability insights using the Model Context Protocol (MCP).

The Expense Tracker MCP Server provides a complete financial tracking engine that integrates budgeting, expense ingestion, smart category detection, and affordability analytics—all via the Model Context Protocol so AI assistants can interact with your financial data safely and intelligently.

🚀 Features

✅ Budget Management

Create total-only or category-based monthly budgets
Validate category allocations and auto-suggest corrections
Convert budgets from total-only → category-mode
Graceful error handling and flexible month parsing

✅ Expense Management

Add expenses with smart category & subcategory detection
Auto date parsing ("yesterday", "next Monday", "Jan 5")
Duplicate detection and budget impact analysis
Bulk add expenses (NLP friendly, validated, error-tolerant)
Update & delete expenses with validation & safety prompts

✅ Affordability Engine

Predict affordability before adding expenses
Total-budget and category-budget aware
Impact percentage + status levels
Consistent logic across all modules

✅ Insights & Analytics

Summaries by month, category, or date ranges
Remaining budget calculations and trend extraction
Days remaining in month tracking
Human-readable status indicators

✅ Smart Category Detection

AI-powered heuristics for auto-category assignment
Keyword extraction and confidence-based assignment
Fallback suggestions when uncertain
Works for both bulk and single expenses

✅ Human-Friendly Design

Suggestions instead of hard errors
Clarification prompts and auto-fixes for common mistakes
Safe delete operations with confirmation
Full MCP-compatible error handling

🏗️ Project Structure

expense-tracker-mcp/
│
├── server.py                  # MCP server entrypoint
├── config.py                  # Category config & paths
│
├── modules/                   # MCP tool implementations
│   ├── budget.py              # Budget tools (set, list, remaining)
│   ├── expenses.py            # Add, update, delete, bulk-add
│   ├── affordability.py       # Affordability analysis
│   ├── search.py              # Query expenses/budgets
│   └── insights.py            # Higher-level analytics
│
├── utils/                     # Core business logic
│   ├── database.py            # SQLite connection + init
│   ├── budget_core.py         # Core budget logic
│   ├── expenses_core.py       # Core DB I/O for expenses
│   ├── affordability_core.py  # Core affordability logic
│   ├── category_detection.py # Keyword & heuristic-based detection
│   ├── date_utils.py          # Flexible date parsing
│   ├── status.py              # Budget status levels
│   └── __init__.py            # Aggregated exports
│
├── data/
│   ├── budgets.json           # Stored budget data
│   └── expenses.db            # SQLite expense database
│
└── resources/
    └── categories.json        # Category → subcategories mapping

⚙️ Installation & Setup

1. Clone the Repository

git clone https://github.com/Khushi-c-sharma/expense-tracker-mcp-server-improvised.git
cd expense-tracker-mcp

2. Create and Activate a Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.\.venv\Scripts\activate

# Activate (macOS/Linux)
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Initialize the Database

The server automatically initializes the SQLite database on startup—no manual setup required.

5. Run the Server

For Claude Desktop integration:

fastmcp dev server.py

For testing/development:

fastmcp run server.py

🔌 Claude Desktop Integration

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "dev",
        "/absolute/path/to/expense-tracker-mcp/server.py"
      ]
    }
  }
}

Replace /absolute/path/to/ with your actual path, then restart Claude Desktop.

🧰 Available Tools

🔹 Budget Tools

Tool	Description
`set_monthly_budget`	Set total or category-based budgets
`get_remaining_budget`	Check remaining money by month/category
`list_budgets`	View all budget configurations
`convert_to_category_budget`	Transform simple budgets into category budgets

🔹 Expense Tools

Tool	Description
`add_expense`	Add expenses with smart category detection
`bulk_add_expenses`	Add multiple expenses at once (validated & robust)
`update_expense`	Safely update amount/category/date/description
`delete_expense`	Safe delete with confirmation
`get_category_info`	Get rules for categories/subcategories

🔹 Affordability Tools

Tool	Description
`check_affordability`	Predict impact before adding an expense

🔹 Insights Tools

Tool	Description
`monthly_summary`	Summaries of spending by month
`category_breakdown`	Category-level insights
`remaining_days_info`	Insights with days remaining

🔹 Search Tools

Tool	Description
`search_expenses`	Query expenses by text/category/date
`search_budget`	Find budgets easily
`smart_lookup`	Intelligent search ("What did I spend on food last week?")

🧪 Testing

To ensure module compatibility and catch issues early:

pip install pytest
python -m pytest -q

Our tests verify that all modules load without import errors, validate API shapes, and catch schema issues before deployment.

🎯 Design Philosophy

✔ Human-First UX

Errors guide users with suggestions rather than blocking them completely.

✔ Strict Tool API Discipline

MCP-safe signatures (no **kwargs), predictable schemas, and consistent behavior.

✔ Separation of Concerns

modules/ → Conversational logic and MCP tool implementations
utils/ → Pure core business logic
server.py → MCP integration layer

✔ Extensible Architecture

Adding new tools or insights is straightforward thanks to the modular design.

📈 Future Enhancements

💬 Contributing

We welcome contributions! Feel free to open issues or pull requests to:

Add new features
Improve category detection heuristics
Suggest new insights and analytics
Expand test coverage
Improve documentation

📝 License

[Add your license here - MIT, Apache 2.0, etc.]

🧠 About

This project was built to serve as the backend brain for AI budgeting assistants using the Model Context Protocol. It emphasizes:

Reliability → Robust error handling and validation
Explainability → Clear feedback and suggestions
Graceful Handling → User-friendly error messages
Human-Friendly Responses → Natural language interactions

Your server is now one of the most feature-rich MCP financial engines available, ready to power intelligent personal finance assistants.

🙏 Acknowledgments

Built with FastMCP and powered by the Model Context Protocol.