ClearFi Finance Server

Give your AI assistant a clear picture of your finances. This MCP server connects Claude (or any MCP-compatible AI) to the ClearFi personal finance API, providing tools to search transactions, track bills, analyze spending, and manage accounts.

The AI helps you see your financial data clearly — it doesn't make decisions for you.

What It Does

• Search and categorize bank transactions
• Track recurring bills and income with a financial calendar
• Analyze spending by category or merchant
• Manage bank accounts (Plaid-connected and manual)
• Import transactions from CSV files
• Sync fresh data from connected banks
• Match transactions to scheduled bills

Prerequisites

• Python 3.10+
• A ClearFi account with an API key
• Network access to the ClearFi API

Install

git clone https://github.com/YOUR_USERNAME/clearfi-finance-mcp.git
cd clearfi-finance-mcp
pip install -r requirements.txt

Or install dependencies directly:

pip install fastmcp httpx

Get an API Key

1. Log in to ClearFi
2. Go to Settings > AI Agents
3. Click Create Agent, choose a role and permissions
4. Copy the API key (shown once)

Configure

Claude Code

Add to your project's .mcp.json (or ~/.claude/settings.json for global access):

{
  "mcpServers": {
    "clearfi-finance": {
      "command": "python",
      "args": ["/path/to/clearfi-finance-mcp/mcp_server.py"],
      "env": {
        "API_URL": "https://aifinancial.thehandle.app/api",
        "API_KEY": "gcal_your_api_key_here"
      }
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "clearfi-finance": {
      "command": "python",
      "args": ["/path/to/clearfi-finance-mcp/mcp_server.py"],
      "env": {
        "API_URL": "https://aifinancial.thehandle.app/api",
        "API_KEY": "gcal_your_api_key_here"
      }
    }
  }
}

Using uv (alternative)

If you use uv instead of pip:

{
  "mcpServers": {
    "clearfi-finance": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/clearfi-finance-mcp/mcp_server.py"],
      "env": {
        "API_URL": "https://aifinancial.thehandle.app/api",
        "API_KEY": "gcal_your_api_key_here"
      }
    }
  }
}

Available Tools

Tool	Description
list_accounts	List all bank accounts with balances and types
search_transactions	Search transactions with date, amount, merchant, category, and institution filters
categorize_transaction	Set the category on a transaction
delete_transaction	Delete a transaction (two-step confirmation)
analyze_spending	Analyze spending grouped by category or merchant
get_financial_summary	Comprehensive summary: balances, monthly spending/income, upcoming bills
list_categories	List all transaction categories
sync_transactions	Sync fresh transactions from connected banks
list_scheduled_transactions	List recurring bills and income
create_scheduled_transaction	Create a new recurring bill or income
update_scheduled_transaction	Update a scheduled transaction
delete_scheduled_transaction	Delete a scheduled transaction
list_upcoming_occurrences	List upcoming bill/income occurrences for the next N days
mark_bill_paid	Mark a bill occurrence as paid
skip_occurrence	Skip a bill occurrence without affecting the schedule
unskip_occurrence	Revert a skipped occurrence back to pending
match_transaction	Link a bank transaction to a scheduled occurrence
unmatch_transaction	Unlink a matched occurrence
list_manual_institutions	List manually-added banks and their accounts
create_manual_institution	Add a bank that Plaid doesn't support
rename_manual_institution	Rename a manual institution
delete_manual_institution	Delete a manual institution and its data
create_manual_account	Add an account under a manual institution
delete_manual_account	Delete a manual account and its transactions
import_csv_preview	Upload a CSV and preview columns before importing
import_csv_confirm	Confirm and import transactions from a previewed CSV

Resources (Auto-loaded Context)

Resource	Description
account://balances	Current balances for all linked accounts
transactions://recent	Last 50 transactions
bills://upcoming	Bills and income due in the next 30 days

Example Prompts

Once configured, try asking your AI:

• "What are my account balances?"
• "How much did I spend on groceries this month?"
• "Show me all transactions from Chase over $50"
• "What bills are coming up in the next two weeks?"
• "Create a monthly expense called Rent for $1500 starting March 1st"
• "Categorize that Starbucks transaction as Dining"
• "Sync my latest transactions from the bank"

Security

• The MCP server script contains no secrets — API keys are passed via environment variables
• API keys are scoped by role (viewer/member) and permissions (read/write per data type)
• Each AI agent can be restricted to specific bank accounts
• Keys can be revoked at any time from the ClearFi settings page

License

MIT