Sure MCP Server

A Model Context Protocol (MCP) server for integrating with the Sure self-hosted personal finance platform. This server provides access to your financial accounts, transactions, categories, and AI chat through Claude Desktop.

Quick Start

There are two ways to run the Sure MCP Server: Docker (recommended) or manual installation.

Option A: Docker Installation (Recommended)

1. Build the Docker image:

   docker compose build

2. Configure Claude Desktop to use Docker:

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

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "Sure": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e", "SURE_API_URL",
           "-e", "SURE_API_KEY",
           "-e", "SURE_VERIFY_SSL",
           "--add-host=host.docker.internal:host-gateway",
           "sure-mcp-server"
         ],
         "env": {
           "SURE_API_URL": "http://host.docker.internal:3000",
           "SURE_API_KEY": "your-api-key-here",
           "SURE_VERIFY_SSL": "false"
         }
       }
     }
   }

   Note: Use host.docker.internal to connect to Sure running on your host machine.

3. Restart Claude Desktop

Option B: Manual Installation

1. Clone this repository:

   git clone https://github.com/robcerda/sure-mcp-server.git
   cd sure-mcp-server

2. Install dependencies:

   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

   {
     "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

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

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