💰 ExpenseTracker MCP Server

A lightweight and scalable Expense Tracking MCP Server built using FastMCP and SQLite. This server allows you to add, list, and summarize expenses efficiently, making it ideal for personal finance management or integration with MCP-compatible clients like Claude Desktop.

---

🚀 Features

• ✅ Add expenses with category and notes
• 📊 List expenses within a date range
• 📈 Summarize expenses by category
• 📂 Default categories support (with fallback)
• ⚡ Async database operations using aiosqlite
• ☁️ Cloud-ready (FastMCP deployment compatible)

---

🛠️ Tech Stack

• Python
• FastMCP
• SQLite (aiosqlite for async support)

---

📁 Project Structure

.
├── main.py              # Main MCP server file
├── requirements.txt    # Dependencies
├── categories.json     # (Optional) Custom categories
└── README.md

---

⚙️ Setup & Installation

1. Clone the repository

git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name

2. Create virtual environment

python -m venv venv
venv\Scripts\activate   # Windows

3. Install dependencies

pip install -r requirements.txt

---

▶️ Running the Server

python main.py

Server will start at:

http://0.0.0.0:8000

---

🌐 MCP Endpoint

Once deployed on FastMCP, your endpoint will look like:

https://your-app-name.fastmcp.app/mcp

⚠️ Note: Authentication is required to access this endpoint.

---

📌 Available Tools

➤ Add Expense

Adds a new expense entry.

Parameters:

• date (YYYY-MM-DD)
• amount (float)
• category (string)
• subcategory (optional)
• note (optional)

---

➤ List Expenses

Fetch expenses within a date range.

Parameters:

• start_date
• end_date

---

➤ Summarize Expenses

Get category-wise expense summary.

Parameters:

• start_date
• end_date
• category (optional)

---

📂 Categories Resource

Endpoint:

expense:///categories

• Loads from categories.json if available
• Falls back to default categories if file is missing

---

🧠 How It Works

• Uses a temporary directory for database storage
• Initializes database on startup
• Uses async operations for better performance
• Safe fallback mechanisms for missing files

---

⚠️ Common Issues & Fixes

❌ Pre-flight check failed

• Ensure your file name is main.py
• Make sure mcp = FastMCP(...) is correct
• Check logs for missing dependencies

❌ Module not found

• Add missing packages to requirements.txt

Example:

fastmcp
aiosqlite

---

💡 Future Improvements

• User authentication system
• Dashboard UI
• Monthly budget tracking
• Data export (CSV/Excel)

---

👨‍💻 Author

Built with ❤️ for learning and real-world MCP integration.

---

⭐ Support

If you like this project:

• Star ⭐ the repo
• Share with others
• Contribute improvements

---