# 💰 Finance MCP Server

A personal finance tracker powered by the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing you to manage your income and expenses directly through Claude Desktop using natural language.

---

## 🚀 Features

- Add income and expense transactions
- Check your current balance
- List recent transactions
- Get a summary grouped by category
- Get a monthly summary (income, expenses, balance)
- Delete transactions by ID
- Persistent storage using **SQLite**

---

## 🛠️ Requirements

- Python 3.10+
- [Claude Desktop](https://claude.ai/download)

---

## 📦 Installation

**1. Clone the repository:**
```bash
git clone https://github.com/taylor3lewis/finance-mcp-server.git
cd finance-mcp-server
```

**2. Create and activate a virtual environment:**
```bash
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate
```

**3. Install dependencies:**
```bash
pip install -r requirements.txt
```

---

## ⚙️ Claude Desktop Configuration

Open your Claude Desktop config file:

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

Add the following entry inside `"mcpServers"`:

```json
{
  "mcpServers": {
    "finance-mcp-server": {
      "command": "C:/path/to/your/venv/Scripts/python.exe",
      "args": ["C:/path/to/finance-mcp-server/server.py"]
    }
  }
}
```

> ⚠️ Replace the paths with the actual paths on your machine.

Restart Claude Desktop after saving the config file.

---

## 🧰 Available Tools

| Tool | Description |
|------|-------------|
| `add_transaction` | Add an income or expense transaction |
| `get_balance` | Get your current balance |
| `list_transactions` | List the most recent transactions |
| `get_summary_by_category` | View totals grouped by category |
| `get_monthly_summary` | View income, expenses and balance for a given month |
| `delete_transaction` | Delete a transaction by its ID |

---

## 💬 Usage Examples

Once configured, just talk to Claude naturally:

> *"Mock 10 fake expenses in 3 different categories: food, leisure, and bills."*

![Usage 1](docs/screenshot_1.png)

> *"What is my current balance?"*
> 
![Usage 2](docs/screenshot_2.png)

> *"Show me a summary of my expenses by category"*
> 
![Usage 3](docs/screenshot_3.png)

> *"If I maintain this monthly spending pattern, how much will I have spent by the end of the year?"*
> 
![Usage 4](docs/screenshot_4.png)

> *"How much did I spend in March 2026"*

![Usage 5](docs/screenshot_5.png)

> *"List my last 5 transactions"*

![Usage 6](docs/screenshot_6.png)

> *"delete entry with id = 2"*

![Usage 7](docs/screenshot_7.png)


### Using HTTP Client

Run MCP Server

```
python main.py http
```

Run Client in Another Shell

```
python client.py
```

![Usage 8](docs/screenshot_8.png)

---

## 🗂️ Project Structure

```
finance-mcp-server/
├── main.py            # MCP server with all tools
├── client.py          # MCP client to connect to server via API
├── requirements.txt   # Python dependencies
├── README.md          # Project documentation
└── data/
    └── finance.db     # SQLite database (auto-created on first run)
```

---