Expense Tracker MCP Server
# 💸 Expense Tracker MCP Server
A professional Model Context Protocol (MCP) server designed to help you track, analyze, and optimize your personal finances. This server provides tools to add expenses, list transactions, and generate detailed financial summaries with **Indian Rupee (₹)** support and strategic advice.
## 🚀 Features
- **Add Expenses**: Easily log expenses with categories, dates, and notes.
- **Tabular Summaries**: Professional reports in tabular format showing counts, totals, and percentages.
- **Financial Advice**: Strategic solutions tailored to your spending habits (Needs vs. Wants).
- **Visual Graphs**: Built-in support for **Mermaid.js** charts and **Matplotlib** PNG graphs for visual distribution.
- **INR Support**: All financial values are formatted in Indian Rupees (₹).
## 🛠️ Installation
### 1. Clone the Repository
```bash
git clone https://github.com/your-username/expense-tracker.git
cd expense-tracker
```
### 2. Install Dependencies (Recommended: `uv`)
If you have `uv` installed, simply run:
```bash
uv sync
```
Alternatively, using standard `pip`:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
## 🖥️ Usage
### Running the Server
If using `uv`, you can run the server directly:
```bash
uv run main.py
```
Otherwise, use python:
```bash
python main.py
```
### Claude Desktop Integration
To use this with Claude Desktop, add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"Expense Tracker": {
"command": "uv",
"args": ["--directory", "C:/path/to/expense-tracker", "run", "main.py"]
}
}
}
```
*Note: Replace `C:/path/to/` with the actual absolute path to your project directory.*
## 📂 Project Structure
- `main.py`: The core MCP server implementation.
- `expenses.db`: SQLite database for persistent storage.
- `requirements.txt`: List of Python dependencies.
- `pyproject.toml`: Project configuration for tools like `uv`.
## 🧠 Smart Tools
- `add_expense`: Add a new expense record.
- `list_expenses`: Retrieve transactions within a date range.
- `summarize`: Get a detailed financial report with graphs and advice.
- `categories`: List all supported expense categories.
## ⚖️ License
MIT
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: adding an expense, listing expenses, and summarizing/analyzing them. There is no overlap in their core functions, making it easy for an agent to choose the right tool.
Most tools follow the verb_noun pattern (add_expense, list_expenses), but 'summarize' lacks an object, deviating from the pattern. There is also a minor singular/plural inconsistency between 'expense' and 'expenses'. Overall the convention is readable and predictable.
With only three tools, the set is minimal but appropriate for a simple expense tracker. The count is not excessively thin (like 1-2) and stays within a reasonable scope, though one could imagine additional tools for management.
The server covers creating and reading expenses, plus a summary/analysis function, but lacks update and delete operations. For an expense tracker, the inability to modify or remove expenses is a notable gap that agents would have to work around.