wallet-mcp

An MCP server for the BudgetBakers Wallet REST API. Runs as a persistent HTTP service using MCP's Streamable HTTP transport — meant to be run as a long-lived background process (e.g. via systemd) that MCP clients connect to over the network, rather than a stdio subprocess a client spawns itself.

Covers the full Wallet API: Records (transactions), Accounts, Categories, Budgets, Labels, Standing Orders (recurring payments, read + delete only — creating/editing one requires the Wallet app), Goals (read-only), Record Rules (auto-categorization, read + delete only), and API usage stats.

Prerequisites

• Node.js 18 or newer (node --version)
• A BudgetBakers Wallet account on the Premium plan — the REST API isn't available on the free plan
• An MCP client that supports Streamable HTTP transport (Claude Code, or any custom MCP client)

Setup

git clone https://github.com/kirikatiya/wallet-mcp.git
cd wallet-mcp
npm install
npm run build

Generate an API token at https://web.budgetbakers.com/settings/rest-api — keep it secret, don't commit it anywhere. Unlike a typical stdio MCP server, the token is not configured on the server at all: each MCP client sends its own token per request via the standard Authorization: Bearer <token> HTTP header, and the server forwards it straight through to the Wallet API. This lets multiple callers/agents share one running instance, each using their own Wallet account. (If you do want a single fixed token for every caller instead, set WALLET_API_TOKEN in the server's environment — it's used as a fallback whenever a request has no Authorization header.)

Running it

npm start

By default it listens on http://127.0.0.1:7691/mcp — loopback only, not reachable from the network, since it's designed to be called by other processes/agents on the same machine. Override with the WALLET_MCP_HOST / WALLET_MCP_PORT env vars if needed.

As a background service (systemd)

A ready-to-adapt unit is in systemd/wallet-mcp.service.example. To install as a per-user service (no root required):

cp systemd/wallet-mcp.service.example ~/.config/systemd/user/wallet-mcp.service
# edit the paths inside to match where you cloned the repo
systemctl --user daemon-reload
systemctl --user enable --now wallet-mcp.service
loginctl enable-linger "$USER"   # keeps it running after you log out

Check it's up: systemctl --user status wallet-mcp.service and curl -s -X POST http://127.0.0.1:7691/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'.

⚠️ If you ever change the bind host to something other than 127.0.0.1 (e.g. to allow access from other machines), put it behind a firewall/VPN — the server has no authentication of its own beyond forwarding whatever Authorization header it receives.

Register with an MCP client

Claude Code

claude mcp add --transport http wallet http://127.0.0.1:7691/mcp \
  --header "Authorization: Bearer <your_token>"

Verify it's connected with claude mcp list, then ask Claude something like "list my Wallet accounts" to confirm it can reach the API.

Other MCP clients

Point the client at http://127.0.0.1:7691/mcp using Streamable HTTP transport, and configure it to send Authorization: Bearer <your_token> with each request — consult your client's docs for where custom headers are set on an HTTP MCP server entry.

Tools

Tool	Description
wallet_list_records	List transactions — pagination + filters on account/date/category/label/note/payee/amount/type/state/source
wallet_get_record	Get one record by ID
wallet_create_records	Create up to 50 transactions
wallet_update_records	Patch up to 10 transactions ($clear, place, labelIds add/remove, transfer edits)
wallet_delete_records	Delete up to 10 transactions
wallet_record_references	Check what references given records
wallet_list_accounts	List accounts
wallet_get_account	Get one account by ID
wallet_create_account	Create an account
wallet_update_accounts	Patch up to 10 accounts
wallet_delete_accounts	Delete up to 10 accounts
wallet_account_references	Check what references given accounts
wallet_list_categories	List categories (system + custom)
wallet_get_category	Get one category by ID
wallet_create_category	Create a custom category
wallet_update_categories	Patch up to 10 categories
wallet_delete_categories	Delete up to 10 custom categories
wallet_category_references	Check what references given categories
wallet_list_budgets	List budgets
wallet_get_budget	Get one budget by ID
wallet_create_budget	Create a budget
wallet_update_budgets	Patch up to 10 budgets (limits, overrides, tracked accounts/categories/labels)
wallet_delete_budgets	Delete up to 10 budgets
wallet_list_labels	List labels/hashtags
wallet_get_label	Get one label by ID
wallet_create_label	Create a label
wallet_update_labels	Patch up to 10 labels
wallet_delete_labels	Delete up to 10 labels
wallet_label_references	Check what references given labels
wallet_list_standing_orders	List recurring payments (read-only — create/edit needs the Wallet app)
wallet_get_standing_order	Get one standing order by ID
wallet_list_standing_order_items	List standing-order occurrences (due/paid/dismissed history)
wallet_delete_standing_orders	Delete up to 10 standing orders
wallet_list_goals	List savings goals (fully read-only)
wallet_get_goal	Get one goal by ID
wallet_list_record_rules	List auto-categorization rules (read + delete only)
wallet_get_record_rule	Get one record rule by ID
wallet_delete_record_rules	Delete up to 10 record rules
wallet_api_usage_stats	Get REST API usage stats for the calling token

Notes

• Batch write endpoints (POST/PATCH/DELETE with multiple items) can return HTTP 207 with a mix of per-item successes and failures; that's returned as normal tool output, not an error.
• Wallet rate-limits at 300 requests/hour per token. Tool responses append a warning once the X-RateLimit-Remaining header drops to 5 or below.
• Filter parameters on wallet_list_records accept the API's gte./lte./contains./ contains-i. prefix syntax (e.g. "gte.100"), or a plain value for exact match.
• Each MCP request is stateless: the server doesn't persist sessions between calls, so there's nothing to clean up if a client disconnects mid-conversation.

Troubleshooting

• "No Wallet API token available" — neither the request's Authorization header nor the server's WALLET_API_TOKEN env var provided a token. Check your client is sending the header on every request, not just at connection time.
• HTTP 401/404 from the API with a token set — token is invalid, expired, or was revoked; generate a new one at https://web.budgetbakers.com/settings/rest-api.
• HTTP 403 / a "Premium required" style message — the REST API needs an active Wallet Premium subscription.
• HTTP 429 — you've hit the 300 requests/hour limit; wait for it to reset or reduce call frequency.
• Client can't connect — confirm the service is actually running (systemctl --user status wallet-mcp.service or curl the /mcp endpoint) and that the client is configured for Streamable HTTP, not stdio.

Development

npm run dev    # tsc --watch
npm start      # run the built server

License

MIT