robcerda/sure-mcp-server

5 stars 9 forks Quality 69 Trend 13MIT

A Model Context Protocol (MCP) server for integrating with the Sure self-hosted personal finance platform.

Overview

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. 3. : Add this to your Claude Desktop configuration file: : ~/Library/Application Support/Claude/claude_desktop_config.json : %APPDATA%\Claude\claude_desktop_config.json : Replace /path/to/your/sure-mcp-server with your actual path! 1. Start your Sure Docker instance: docker compose up -d 2. Log into Sure at http://localhost:3000 3. Go to and generate a new key 4. Copy the API key to your Claude Desktop config 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 For local Docker setup, use SURE_API_URL=http://localhost:3000 and SURE_VERIFY_SSL=false.

README

Sure MCP Server

Quick Start

1. Installation

Clone this repository:

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

Install dependencies:

pip install -r requirements.txt
pip install -e .

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!

Restart Claude Desktop

2. Get Your Sure API Key

Start your Sure Docker instance: docker compose up -d
Log into Sure at http://localhost:3000
Go to Settings > API Key and generate a new key
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

Verify Sure is running: docker compose ps
Check the API URL is correct
Try check_connection tool to diagnose

Authentication Issues

Verify your API key is correct
Check the key hasn’t expired
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

View the full README on GitHub

Install

This server does not publish a one-line install command.

Open the repository installation guide New to MCP? Start with the mcpskill.org guide →

Configuration

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