# Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking personal expenses with SQLite database storage. This server integrates with Claude Desktop to provide expense management capabilities through natural language.

## Features

* ✅ Add, update, and delete expenses
* ✅ List expenses by date range
* ✅ Summarize expenses by category
* ✅ Flexible deletion by multiple criteria
* ✅ Predefined expense categories
* ✅ SQLite database for persistent storage
* ✅ Local and remote deployment options

## Quick Start Options

Choose the setup method that works best for you:

### Option 1: Direct Remote Server (Instant Setup - Claude Pro Only)

**⚠️ Requires Claude Pro subscription** - Direct URL connections are a Pro feature.

Connect directly to the deployed remote server without any local setup:

1. Open Claude Desktop configuration file:
   * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   * **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. Add this configuration:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "url": "https://boiling-aqua-trout.fastmcp.app/mcp"
    }
  }
}
```

3. Restart Claude Desktop
4. Start tracking expenses immediately! 🎉

**Note**: This remote server is hosted on FastMCP Cloud. Your data is stored on the remote server.

**Don't have Claude Pro?** Use Option 2 below to connect via a local proxy server!

---

### Option 2: Local Proxy to Remote Server (For Free Users & Customization)

**✅ Works with Claude Free plan!** Run a local MCP server that proxies requests to the remote server. This is the way to access remote MCP servers if you don't have Claude Pro.

**Use cases:**
- Connect to remote servers on Claude Free plan
- Add custom logging or middleware
- Run locally while using remote data
- Extend functionality with additional features

#### Setup Steps:

1. **Install uv** (if not already installed):

**Windows (PowerShell):**
```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS/Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. **Create a new project**:

```bash
mkdir expense-tracker-proxy
cd expense-tracker-proxy
uv init .
```

3. **Install FastMCP**:

```bash
uv add fastmcp
```

4. **Create proxy server** (`main.py`):

```python
from fastmcp import FastMCP

mcp = FastMCP.as_proxy(
    "https://boiling-aqua-trout.fastmcp.app/mcp",
    name="expense tracker remote proxy server"
)

if __name__ == "__main__":
    mcp.run()
```

5. **Configure Claude Desktop**:

```json
{
  "mcpServers": {
    "expense-tracker-proxy": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YOUR_USERNAME/path/to/expense-tracker-proxy",
        "run",
        "main.py"
      ]
    }
  }
}
```

**Important**: Replace the path with your actual project directory.

6. **Restart Claude Desktop**

**Benefits of Proxy Approach:**
- Add custom logging or middleware
- Modify requests/responses before forwarding
- Run locally but leverage remote infrastructure
- Easy to extend with additional features

---

### Option 3: Full Local Installation (Complete Control & Privacy)

For those who want full control, privacy, and the ability to modify the core server logic.

## Prerequisites

* Python 3.10 or higher
* [uv](https://github.com/astral-sh/uv) package manager
* Claude Desktop app

## Installation

### 1. Install uv

**Windows (PowerShell):**

```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS/Linux:**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Clone or Create Project

```bash
# Clone this repository
git clone https://github.com/Sudhanvaha/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

# OR create from scratch
mkdir expense-tracker-mcp-server
cd expense-tracker-mcp-server
uv init .
```

### 3. Install Dependencies

```bash
# Install required packages
uv add fastmcp
```

### 4. Create the Server

Copy the full `main.py` code from this repository into your project.

### 5. Test the Server

```bash
# Run the server
uv run main.py
```

### 6. Configure Claude Desktop for Local Server

1. Open Claude Desktop configuration file (locations mentioned above)

2. Add the MCP server configuration:

```json
{
  "mcpServers": {
    "expense-tracker-local": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YOUR_USERNAME/path/to/expense-tracker-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}
```

**Important**: Replace the path with your actual project directory path.

3. Restart Claude Desktop

---

## Usage

Once configured (via any method), you can interact with the expense tracker through Claude using natural language:

### Add Expense

```
"Add an expense: $50 for groceries on 2024-12-14"
"Log $25.50 spent on transport today with note 'Uber to office'"
```

### List Expenses

```
"Show me all expenses from December 1 to December 14, 2024"
"List my expenses for last week"
```

### Update Expense

```
"Update expense ID 5 to $75"
"Change the category of expense 3 to 'entertainment'"
```

### Delete Expense

```
"Delete expense with ID 5"
"Remove all food expenses from last week"
"Delete expenses in the transport category"
```

### Summarize Expenses

```
"Summarize my expenses by category for December 2024"
"What's my total spending on food this month?"
```

### View Categories

```
"What expense categories are available?"
"Show me the list of categories"
```

## Available Tools

### `add_expense`

Add a new expense to the tracker.

**Parameters:**

* `date` (string): Date in YYYY-MM-DD format
* `amount` (float): Expense amount
* `category` (string): Expense category
* `subcategory` (string, optional): Subcategory
* `note` (string, optional): Additional notes

### `list_expenses`

List all expenses within a date range.

**Parameters:**

* `start_date` (string): Start date (YYYY-MM-DD)
* `end_date` (string): End date (YYYY-MM-DD)

### `update_expense`

Update an existing expense (only provided fields will be updated).

**Parameters:**

* `cid` (int): Expense ID to update
* `date` (string, optional): New date
* `amount` (float, optional): New amount
* `category` (string, optional): New category
* `subcategory` (string, optional): New subcategory
* `note` (string, optional): New note

### `delete_expense`

Delete expenses based on various criteria.

**Parameters:**

* `id` (int, optional): Delete by ID
* `date` (string, optional): Delete by date
* `category` (string, optional): Delete by category
* `subcategory` (string, optional): Delete by subcategory
* `amount` (float, optional): Delete by amount
* `note` (string, optional): Delete by note
* `start_date` & `end_date` (strings, optional): Delete by date range

### `summarize_expenses`

Get expense summaries grouped by category.

**Parameters:**

* `start_date` (string): Start date (YYYY-MM-DD)
* `end_date` (string): End date (YYYY-MM-DD)
* `category` (string, optional): Filter by specific category

## Available Resources

### `expense://categories`

Returns the list of available expense categories in JSON format.

## Database Schema

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

## File Structure

**For Full Local Installation:**
```
expense-tracker-mcp-server/
├── main.py              # MCP server code
├── expense.db           # SQLite database (auto-created)
├── categories.json      # Categories list (auto-created)
├── pyproject.toml       # uv project configuration
└── README.md            # This file
```

**For Proxy Setup:**
```
expense-tracker-proxy/
├── main.py              # Proxy server code (5 lines!)
└── pyproject.toml       # uv project configuration
```

## Default Categories

The server comes with these default categories:

* food
* transport
* entertainment
* utilities
* healthcare

You can modify `categories.json` to add or remove categories (local installation only).

## Deployment Options Comparison

| Feature | Direct Remote (Pro) | Local Proxy (Free/Pro) | Full Local |
|---------|-------------------|----------------------|------------|
| Claude Plan | **Pro only** | **Free & Pro** | Free & Pro |
| Setup Time | 2 minutes | 5 minutes | 15-20 minutes |
| Privacy | Remote storage | Remote storage | Complete privacy |
| Customization | None | Middleware only | Full control |
| Maintenance | Zero | Minimal | Manual updates |
| Internet Required | Yes | Yes | No |
| Code Required | No | 5 lines | Full codebase |
| Cost | Pro subscription | Free | Free |

## Troubleshooting

### Server not appearing in Claude Desktop

1. Check the configuration file path is correct
2. Ensure the `command` path points to your project directory (for local/proxy setup)
3. Verify the remote URL is correct (for direct remote setup)
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors

### Remote Server Issues

If the remote server isn't responding:
1. Check your internet connection
2. Verify the URL: `https://boiling-aqua-trout.fastmcp.app/mcp`
3. Try removing and re-adding the configuration
4. Contact me via GitHub issues if the problem persists

### Proxy Server Issues

If the proxy isn't working:
1. Test the proxy server independently: `uv run main.py`
2. Check if the remote URL is accessible
3. Verify your FastMCP installation: `uv add fastmcp`
4. Check Claude Desktop configuration paths

### Database errors (Local Installation Only)

If you encounter database errors:

```bash
# Delete the database to reset
rm expense.db

# Restart the server to recreate the database
uv run main.py
```

### Import errors

```bash
# Reinstall dependencies
uv sync
```

## Development

### Extending the Proxy Server

You can add custom logic to the proxy server:

```python
from fastmcp import FastMCP

mcp = FastMCP.as_proxy(
    "https://boiling-aqua-trout.fastmcp.app/mcp",
    name="expense tracker remote proxy server"
)

# Add custom logging
@mcp.tool()
def log_expense_activity():
    """Log all expense activities"""
    # Your custom logging logic here
    pass

if __name__ == "__main__":
    mcp.run()
```

### Modifying the Full Server

To modify the server:

1. Edit `main.py`
2. Test changes: `uv run main.py`
3. Restart Claude Desktop to load changes

## Deploying Your Own Remote Server

Want to deploy your own version on FastMCP Cloud?

1. Sign up at [FastMCP Cloud](https://fastmcp.com)
2. Follow their deployment instructions
3. Update the URL in your Claude Desktop configuration or proxy code
4. Share your server URL with others!

## Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

## Roadmap

- [ ] Add budget tracking and alerts
- [ ] Support for multiple currencies
- [ ] Recurring expense templates
- [ ] Export to CSV/Excel
- [ ] Data visualization and charts
- [ ] Multi-user support with authentication
- [ ] Authentication for remote server access

## Support

For issues related to:

* **This Project**: [GitHub Issues](https://github.com/Sudhanvaha/expense-tracker-mcp-server/issues)
* **MCP Protocol**: [MCP Documentation](https://modelcontextprotocol.io)
* **FastMCP**: [FastMCP GitHub](https://github.com/jlowin/fastmcp)
* **Claude Desktop**: [Anthropic Support](https://support.anthropic.com)

## Acknowledgments

Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - Framework for building MCP servers
- [Anthropic Claude](https://www.anthropic.com/claude) - AI assistant platform
- [Model Context Protocol](https://modelcontextprotocol.io) - Standard for AI-application integration

---

⭐ If you find this project helpful, please consider giving it a star on GitHub!

📧 Questions? Open an issue or reach out on [LinkedIn](https://www.linkedin.com/in/sudhanvaha/)