# ExpenseTracker MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for managing personal expenses. Built with [FastMCP](https://github.com/jlouis/fastmcp), this server provides tools for tracking, querying, and summarizing expenses through an AI-ready interface.

## Overview

ExpenseTracker is a lightweight MCP server that enables Claude and other AI applications to:
- **Add expenses** to a SQLite database with categories and notes
- **Query expenses** by date range for review and analysis
- **Summarize expenses** by category to understand spending patterns
- **Manage categories** through a configurable JSON file

This project demonstrates how to build a practical MCP server that integrates with AI assistants for real-world expense management.

## What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI applications to interact with local tools and data sources safely. MCP servers expose resources and tools that AI models can access through a standardized interface, enabling features like:
- Tool use and automation
- Resource access and management
- Server-side processing with client-side oversight

Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io/)

## Features

- 📊 **Add Expenses** - Log expenses with date, amount, category, subcategory, and notes
- 🔍 **Query Expenses** - Retrieve expenses within a date range with full filtering
- 💰 **Summarize Spending** - Get expense totals by category for budget analysis
- 📁 **Category Management** - Maintain a flexible list of expense categories via JSON
- 🗄️ **SQLite Backend** - Persistent storage with no external dependencies
- 🤖 **MCP Integration** - Works seamlessly with Claude and other MCP-compatible clients

## Installation

### Prerequisites

- Python 3.14+
- pip or [uv](https://docs.astral.sh/uv/) package manager

### Setup

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

2. **Create a virtual environment**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -e .
   # Or with uv:
   uv sync
   ```

4. **Create categories file** (optional)
   ```bash
   cat > categories.json << 'EOF'
   {
     "categories": [
       "Food & Dining",
       "Transportation",
       "Entertainment",
       "Shopping",
       "Bills & Utilities",
       "Health & Fitness",
       "Travel",
       "Other"
     ]
   }
   EOF
   ```

## Usage

### Running the Server

Start the MCP server:
```bash
python main.py
```

The server will initialize the SQLite database and listen for MCP connections.

### Available Tools

#### `add_expense`

Add a new expense entry to the database.

**Parameters:**
- `date` (string, required): Date in YYYY-MM-DD format
- `amount` (number, required): Expense amount
- `category` (string, required): Expense category
- `subcategory` (string, optional): Subcategory for detailed tracking
- `note` (string, optional): Additional notes or description

**Example:**
```json
{
  "date": "2024-06-14",
  "amount": 45.50,
  "category": "Food & Dining",
  "subcategory": "Restaurant",
  "note": "Lunch at Italian place"
}
```

#### `list_expenses`

Retrieve expenses within a date range.

**Parameters:**
- `start_date` (string, required): Start date in YYYY-MM-DD format (inclusive)
- `end_date` (string, required): End date in YYYY-MM-DD format (inclusive)

**Example:**
```json
{
  "start_date": "2024-06-01",
  "end_date": "2024-06-30"
}
```

**Returns:** Array of expense objects with id, date, amount, category, subcategory, and note fields.

#### `summarize`

Get a summary of expenses by category within a date range.

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

**Example:**
```json
{
  "start_date": "2024-06-01",
  "end_date": "2024-06-30",
  "category": "Food & Dining"
}
```

**Returns:** Array of category summary objects with category and total_amount fields.

### Resources

#### `expense://categories`

Access the current list of expense categories. The categories file is read fresh on each access, allowing modifications without server restart.

**MIME Type:** `application/json`

## Configuration

### Database

The SQLite database file is stored as `expenses.db` in the project root. The database is automatically initialized on first run with the expenses table.

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

### Categories

Edit `categories.json` to customize the list of expense categories available for your use case. Changes are reflected immediately without restarting the server.

## Project Structure

```
local-mcp-server/
├── main.py              # MCP server implementation
├── expenses.db          # SQLite database (auto-created)
├── categories.json      # Category definitions
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
├── LICENSE             # GPL 3.0 license
└── README.md           # This file
```

## Technical Details

- **Framework:** FastMCP
- **Database:** SQLite3 (built-in Python library)
- **Protocol:** Model Context Protocol (MCP)
- **Language:** Python 3.14+

## Integration with Claude

To use this server with Claude or other MCP clients, configure your client to connect to this server. Consult your client's documentation for MCP server setup instructions.

## Development

### Running Tests

Currently, no automated tests are included. Manual testing via an MCP client is recommended.

### Code Style

The project follows standard Python conventions. Use of type hints and docstrings is encouraged for future contributions.

## License

This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Commit your changes (`git commit -am 'Add new feature'`)
4. Push to the branch (`git push origin feature/your-feature`)
5. Open a Pull Request

## Roadmap

Future enhancements may include:
- [ ] Budget tracking and alerts
- [ ] Recurring expenses
- [ ] Multi-user support
- [ ] Export functionality (CSV, PDF)
- [ ] Advanced analytics and reports
- [ ] Tagging system for expenses
- [ ] Receipt attachment storage

## Support

For issues, questions, or suggestions, please open an issue on GitHub or contact the maintainers.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlouis/fastmcp)
- Implements the [Model Context Protocol](https://modelcontextprotocol.io/)
- Inspired by the need for AI-friendly expense tracking tools