# 💸 Expense Tracker MCP Server

<div align="center">

![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)
![FastMCP](https://img.shields.io/badge/FastMCP-3.4.5+-FF6B6B?style=for-the-badge&logo=fastapi&logoColor=white)
![SQLite](https://img.shields.io/badge/SQLite-003B57?style=for-the-badge&logo=sqlite&logoColor=white)
![UV](https://img.shields.io/badge/uv-Package%20Manager-7C3AED?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)

**A blazing-fast, AI-native Expense Tracker built as an MCP (Model Context Protocol) Server using [FastMCP](https://github.com/jlowin/fastmcp) and SQLite.**

*Plug it directly into Claude Desktop, Cursor, or any MCP-compatible AI client — let your AI manage your finances for you.*

</div>

---

## 📖 Table of Contents

- [What is MCP?](#-what-is-mcp)
- [Features](#-features)
- [Project Structure](#-project-structure)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Running the Server](#-running-the-server)
- [Available Tools](#-available-tools)
- [Connecting to Claude Desktop](#-connecting-to-claude-desktop)
- [Development & Inspection](#-development--inspection)
- [Tech Stack](#-tech-stack)

---

## 🤖 What is MCP?

The **Model Context Protocol (MCP)** is an open standard by Anthropic that allows AI models (like Claude) to securely interact with external tools, APIs, and data sources. This project exposes expense-tracking capabilities as MCP **tools**, meaning you can literally tell Claude:

> *"Add an expense: Coffee, $4.50, Food & Drink, Cash, 2026-08-02"*

...and it will call this server and record it in your local SQLite database — no UI needed.

---

## ✨ Features

- 📝 **Add Expenses** — Record expenses with title, amount, category, payment method, date, and optional description
- 📋 **List Expenses** — Retrieve all stored expenses as structured data
- 🗄️ **Persistent SQLite Storage** — Auto-creates a local `expenses.db` database on first run
- ⚡ **FastMCP Powered** — Minimal boilerplate, maximum capability
- 🔍 **Built-in Inspector** — Visual tool inspector for debugging and testing
- 🔌 **MCP-Compatible** — Works with Claude Desktop, Cursor, and any MCP client

---

## 📁 Project Structure

```
expense_tracker_mcp_server/
├── expense_mcp_server.py      # 🎯 Main MCP server — all tools defined here
├── pyproject.toml             # Project metadata & dependencies
├── uv.lock                    # Locked dependency versions
├── .python-version            # Python version pin
├── .gitignore                 # Git ignore rules
├── src/
│   └── expense_tracker_mcp_server/
│       └── __init__.py        # Package entry point
└── README.md                  # You are here!
```

---

## 🛠️ Prerequisites

Make sure you have the following installed:

- **Python 3.11+**
- **pip** (comes with Python)
- **uv** — Fast Python package manager

---

## 🚀 Installation

### Step 1 — Clone the Repository

```bash
git clone https://github.com/talha963/expense_mcp_server.git
cd expense_mcp_server
```

### Step 2 — Install `uv`

```bash
pip install uv
```

### Step 3 — Initialize the Project with `uv`

```bash
uv init .
```

### Step 4 — Install FastMCP

```bash
# Via pip (global)
pip install fastmcp

# OR via uv (recommended — adds to project)
uv add fastmcp
```

### Step 5 — Sync Dependencies

```bash
uv sync
```

---

## ▶️ Running the Server

### Option 1 — Run directly with Python

```bash
python expense_mcp_server.py
```

> Starts an HTTP server on `http://0.0.0.0:8000`

### Option 2 — Run via `uv`

```bash
uv run expense_mcp_server.py
```

### Option 3 — Run via FastMCP CLI (Recommended for MCP clients)

```bash
uv run --active fastmcp run expense_mcp_server.py
```

---

## 🔧 Available Tools

The server exposes the following MCP tools that AI models can call:

### `add_expense`

Adds a new expense entry to the database.

| Parameter        | Type    | Required | Description                          |
|-----------------|---------|----------|--------------------------------------|
| `title`         | string  | ✅       | Name/title of the expense            |
| `amount`        | float   | ✅       | Amount spent (e.g. `12.50`)         |
| `category`      | string  | ✅       | Category (e.g. `Food`, `Transport`) |
| `payment_method`| string  | ✅       | e.g. `Cash`, `Card`, `Online`       |
| `expense_date`  | string  | ✅       | Date in `YYYY-MM-DD` format          |
| `description`   | string  | ❌       | Optional notes about the expense     |

**Example response:**
```json
{
  "success": true,
  "expense_id": 1,
  "message": "Expense added successfully."
}
```

---

### `list_expenses`

Returns all recorded expenses from the database.

**No parameters required.**

**Example response:**
```json
[
  {
    "id": 1,
    "title": "Coffee",
    "amount": 4.5,
    "category": "Food & Drink",
    "payment_method": "Cash",
    "expense_date": "2026-08-02",
    "description": "Morning coffee at the office"
  }
]
```

---

## 🖥️ Connecting to Claude Desktop

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

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--active",
        "fastmcp",
        "run",
        "/absolute/path/to/expense_mcp_server.py"
      ]
    }
  }
}
```

> **Config file location:**
> - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
> - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

After saving, restart Claude Desktop and the **Expense Tracker** tools will appear automatically.

---

## 🔍 Development & Inspection

Use the **FastMCP Inspector** to visually test and explore your tools in the browser:

```bash
uv run --active fastmcp dev expense_mcp_server.py
```

This opens an interactive web UI where you can:
- See all registered tools
- Call tools manually with test inputs
- Inspect request/response payloads

---

## 🧰 Tech Stack

| Technology | Purpose |
|-----------|---------|
| [FastMCP](https://github.com/jlowin/fastmcp) | MCP server framework |
| [SQLite3](https://docs.python.org/3/library/sqlite3.html) | Lightweight persistent storage |
| [uv](https://github.com/astral-sh/uv) | Ultra-fast Python package manager |
| Python 3.11+ | Runtime |

---

## 👤 Author

**Talha** — [@talha963](https://github.com/talha963)

---

## 📄 License

This project is licensed under the **MIT License** — feel free to use, modify, and distribute.

---

<div align="center">
  <sub>Built with ❤️ using FastMCP — making AI tool integration effortless.</sub>
</div>