# Expense Tracker MCP Server

An AI-powered Expense Tracker built using FastMCP, SQLite, and Claude Desktop.

This MCP (Model Context Protocol) server enables Claude to manage personal expenses, analyze spending patterns, track budgets, generate reports, and export data through natural language conversations.

---

## Features

### Expense Management

* Add expenses
* Update expenses
* Delete expenses
* Search expenses
* List expenses by date range

### Analytics

* Monthly spending reports
* Category-wise spending summaries
* Spending insights
* Largest transactions analysis
* Top spending categories

### Budget Management

* Set monthly budgets
* Track budget utilization
* Monitor remaining budget

### Export

* Export expenses to CSV

### AI Integration

Works with Claude Desktop through MCP.

Example queries:

* "Add ₹250 for lunch today."
* "Show my expenses for June."
* "What was my highest spending category this month?"
* "Have I exceeded my food budget?"
* "Export all expenses from May."

---

## Tech Stack

* Python 3.11+
* FastMCP
* SQLite
* Claude Desktop
* JSON

---

## Project Structure

```text
expense-tracker-mcp-server/
│
├── main.py
├── expenses.db
├── categories.json
├── exports/
│   └── *.csv
├── pyproject.toml
└── README.md
```

---

## Database Schema

### Expenses Table

```sql
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 ''
);
```

### Budgets Table

```sql
CREATE TABLE budgets(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category TEXT UNIQUE NOT NULL,
    monthly_limit REAL NOT NULL
);
```

---

## Installation

### Clone Repository

```bash
git clone https://github.com/your-username/expense-tracker-mcp-server.git

cd expense-tracker-mcp-server
```

### Create Virtual Environment

Windows:

```bash
python -m venv mcp_venv

mcp_venv\Scripts\activate
```

Linux / macOS:

```bash
python -m venv mcp_venv

source mcp_venv/bin/activate
```

### Install Dependencies

```bash
pip install -r requirements.txt
```

or

```bash
pip install fastmcp
```

---

## Running the MCP Server

```bash
python main.py
```

---

## MCP Tools

| Tool              | Description                       |
| ----------------- | --------------------------------- |
| add_expense       | Add a new expense                 |
| list_expenses     | View expenses within a date range |
| update_expense    | Modify an existing expense        |
| delete_expense    | Remove an expense                 |
| search_expenses   | Search expenses by keyword        |
| summarize         | Category-wise spending summary    |
| monthly_report    | Monthly spending statistics       |
| spending_insights | Advanced spending analysis        |
| set_budget        | Create or update a budget         |
| get_budget_status | Track budget utilization          |
| export_csv        | Export expenses to CSV            |

---

## Claude Desktop Integration

Add the following configuration to Claude Desktop:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "python",
      "args": [
        "C:\\path\\to\\expense-tracker-mcp-server\\main.py"
      ]
    }
  }
}
```

Restart Claude Desktop after updating the configuration.

---

## Example Prompts

### Add Expense

```text
Add ₹500 for groceries today.
```

### Get Spending Insights

```text
Give me spending insights for 2026-06.
```

### Budget Tracking

```text
Set my food budget to ₹10000.
```

```text
How much budget is remaining for food this month?
```

### Export Data

```text
Export all expenses from June 2026.
```

---

## Future Improvements

* Income tracking
* Recurring expenses
* Expense forecasting
* AI-generated financial recommendations
* Category trend analysis
* Monthly comparison reports
* Dashboard integration
* Multi-user support
* PostgreSQL support