# 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/)
