# ClearFi Finance MCP Server

Give your AI assistant a clear picture of your finances. This [MCP](https://modelcontextprotocol.io/) 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

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

Or install dependencies directly:

```bash
pip install fastmcp httpx
```

## Get an API Key

1. Log in to [ClearFi](https://aifinancial.thehandle.app)
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):

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

### Claude Desktop

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

```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](https://docs.astral.sh/uv/) instead of pip:

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