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

3. 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)
4. Save the file and restart Claude Desktop
5. 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