📘 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

• [ ] Machine learning–based category predictions
• [ ] OCR receipt scanning → auto expense import
• [ ] Real-time spending limit notifications
• [ ] Expense tagging system
• [ ] Multi-user support
• [ ] CSV/Excel bulk import tools
• [ ] Auto-recurring expenses (rent, subscriptions)
• [ ] Budget forecasting and projections
• [ ] Integration with banking APIs
• [ ] Mobile app companion

---

💬 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.