Wallet BudgetBakers MCP

Wallet by BudgetBakers — MCP Server

Read-only MCP server for accessing Wallet by BudgetBakers financial data from Claude.

Prerequisites

• Wallet Premium subscription (API access requires Premium)
• API token from <https://web.budgetbakers.com/settings/apiTokens>
• Python 3.11+
• uv package manager

Setup

1. Set your API token

export WALLET_API_TOKEN=your_token_here

2. Claude Code (recommended)

The project includes .mcp.json — Claude Code auto-discovers the server. Just open the project directory:

cd wallet-bb-mcp
claude
# /mcp should show "wallet-bb" connected

3. Claude Desktop / Cowork

1. Open Claude Desktop → Settings (gear icon) → Developer → Edit Config
2. This opens claude_desktop_config.json in your editor. Add the mcpServers block:

{
  "mcpServers": {
    "wallet-bb": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/path/to/wallet-bb-mcp", "run", "server.py"],
      "env": {
        "WALLET_API_TOKEN": "your_token_here"
      }
    }
  }
}

1. Replace the values:

• command — full path to uv (run which uv in terminal to get it)
• --directory argument — full path to this project
• WALLET_API_TOKEN — your actual token (env var interpolation doesn't work here)

1. Save the file and restart Claude Desktop
2. You should see an MCP tools indicator (hammer icon) in the chat input area

4. Claude.ai Connector (remote)

The server can be deployed to Google Cloud Run and used as a remote MCP connector:

1. Go to claude.ai → Profile → Settings → Integrations
2. Click Add custom integration
3. Enter the server URL: https://<your-cloud-run-service-url>/mcp
4. No authentication required — the Wallet API token is stored server-side

Cloud Run Deployment

The server supports both local (stdio) and remote (HTTP) transport. Cloud Run deployment is automated via GitHub Actions.

How it works

• Push to main triggers .github/workflows/deploy.yml
• Cloud Build builds the Docker image from Dockerfile
• Cloud Run deploys the new revision to europe-central2
• Auth is handled via Workload Identity Federation (keyless)

Manual deployment

gcloud run deploy wallet-bb-mcp \
  --source . \
  --region europe-central2 \
  --project wallet-bb-mcp \
  --allow-unauthenticated \
  --set-env-vars "WALLET_API_TOKEN=your_token" \
  --port 8080

Local HTTP mode

MCP_TRANSPORT=streamable-http WALLET_API_TOKEN=your_token uv run server.py
# Health check: curl http://localhost:8080/health
# MCP endpoint: http://localhost:8080/mcp

Available Tools

| Tool | Description | |---|---| | get_accounts | List financial accounts (bank, cash, cards). Start here. | | get_records | Get transactions for an account (requires account ID) | | get_records_by_id | Get specific records by IDs (max 30) | | get_categories | List spending/income categories | | get_budgets | List budgets with limits and spent amounts | | get_goals | List savings goals with progress | | get_labels | List custom labels/tags | | get_standing_orders | List recurring payments | | get_record_rules | List auto-categorization rules | | get_api_usage | Check API usage quota |

Filter Syntax

All text fields support filter prefixes:

| Prefix | Example | Meaning | |---|---|---| | eq. | eq.Groceries | Exact match | | contains. | contains.bank | Contains (case-sensitive) | | contains-i. | contains-i.amazon | Contains (case-insensitive) |

Range filters for dates, amounts, and timestamps:

| Prefix | Example | Meaning | |---|---|---| | gte. | gte.2025-01-01 | Greater than or equal | | lte. | lte.2025-12-31 | Less than or equal | | Combined | gte.100,lte.500 | Between 100 and 500 |

Rate Limits

• 500 requests per hour
• Use get_api_usage() to check remaining quota
• Server returns structured error with Retry-After on HTTP 429