# Sure MCP Server

A Model Context Protocol (MCP) server for integrating with the [Sure](https://github.com/we-promise/sure) self-hosted personal finance platform. This server provides access to your financial accounts, transactions, categories, and AI chat through Claude Desktop.

## Quick Start

### 1. Installation

1. **Clone this repository**:
   ```bash
   git clone https://github.com/robcerda/sure-mcp-server.git
   cd sure-mcp-server
   ```

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

3. **Configure Claude Desktop**:
   Add this to your Claude Desktop configuration file:

   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "Sure": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp[cli]",
           "--with-editable",
           "/path/to/your/sure-mcp-server",
           "mcp",
           "run",
           "/path/to/your/sure-mcp-server/src/sure_mcp_server/server.py"
         ],
         "env": {
           "SURE_API_URL": "http://localhost:3000",
           "SURE_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   ```

   **Important**: Replace `/path/to/your/sure-mcp-server` with your actual path!

4. **Restart Claude Desktop**

### 2. Get Your Sure API Key

1. Start your Sure Docker instance: `docker compose up -d`
2. Log into Sure at `http://localhost:3000`
3. Go to **Settings > API Key** and generate a new key
4. Copy the API key to your Claude Desktop config

### 3. Start Using in Claude Desktop

Once configured, use these tools directly in Claude Desktop:
- `get_accounts` - View all accounts
- `get_transactions` - Recent transactions
- `get_categories` - Transaction categories
- `sync_accounts` - Trigger account sync

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `setup_authentication` | Get setup instructions | None |
| `check_auth_status` | Check authentication status | None |
| `check_connection` | Test API connection | None |
| `get_accounts` | Get all financial accounts | None |
| `get_transactions` | Get transactions with filtering | `limit`, `start_date`, `end_date`, `account_ids`, `category_ids`, `search` |
| `get_transaction` | Get single transaction | `transaction_id` |
| `create_transaction` | Create new transaction | `account_id`, `amount`, `name`, `date`, `category_id`, `notes`, `nature` |
| `update_transaction` | Update transaction | `transaction_id`, `amount`, `name`, `date`, `category_id`, `notes` |
| `delete_transaction` | Delete transaction | `transaction_id` |
| `get_categories` | Get all categories | None |
| `get_category` | Get single category | `category_id` |
| `sync_accounts` | Trigger account sync | None |
| `get_usage` | Get API usage info | None |
| `list_chats` | List AI chat sessions | None |
| `create_chat` | Create new chat | `title` |
| `get_chat` | Get chat details | `chat_id` |
| `send_message` | Send message to AI | `chat_id`, `content` |
| `delete_chat` | Delete chat session | `chat_id` |

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SURE_API_URL` | Yes | - | Base URL of your Sure instance |
| `SURE_API_KEY` | Yes | - | API key from Sure settings |
| `SURE_TIMEOUT` | No | 30 | Request timeout in seconds |
| `SURE_VERIFY_SSL` | No | true | Verify SSL certificates |

For local Docker setup, use `SURE_API_URL=http://localhost:3000` and `SURE_VERIFY_SSL=false`.

## Date Formats

- All dates should be in `YYYY-MM-DD` format (e.g., "2024-12-15")
- Transaction amounts: use `nature` field to specify "income" or "expense"

## Troubleshooting

### Connection Issues
1. Verify Sure is running: `docker compose ps`
2. Check the API URL is correct
3. Try `check_connection` tool to diagnose

### Authentication Issues
1. Verify your API key is correct
2. Check the key hasn't expired
3. Regenerate the key in Sure settings

## Project Structure

```
sure-mcp-server/
├── src/sure_mcp_server/
│   ├── __init__.py
│   └── server.py         # Main server implementation
├── pyproject.toml
├── requirements.txt
└── README.md
```

## License

MIT License