xero-mcp
doublebash/xero-mcp
Custom MCP server connecting Claude to Xero accounting (invoices, contacts, bank transactions, reporting) via Cloudflare Workers + OAuth 2.0.
Instalação
npx convez-ai doublebash/xero-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Xero MCP Server
A Model Context Protocol server bridging Claude to Xero accounting, deployed on Cloudflare Workers.
Fork this repo, deploy to your own Cloudflare account, point Claude.ai at your worker, and Claude can read and write your Xero data through natural language — invoices, contacts, bank transactions, payments, P&L, balance sheet.
Built on @bashco/mcp-toolkit — OAuth, per-client bearer tokens, rate limiting, structured logging, and typed tool dispatch are all handled by the shared library.
What Claude gets
- Reading: list/get contacts, invoices, bank transactions, accounts; get P&L, balance sheet
- Writing: create contact, create invoice, email invoice, create payment, create bank transaction
- All operations are scoped to the Xero tenant you authorise during initial OAuth setup
How auth works
Two layers:
- Claude.ai ↔ your worker — standard MCP OAuth 2.0 + PKCE flow. Each Claude client gets a unique bearer token; your
MCP_APPROVAL_CODEis what you paste at/authorizeonce to mint that bearer. - Your worker ↔ Xero — proxied OAuth. You authorise Xero once by visiting
/oauth/starton your deployed worker; tokens are stored encrypted at rest in Cloudflare KV. Refresh is automatic.
Setup — deploy your own copy
Prerequisites
- A Cloudflare account (free plan works)
- Wrangler CLI installed and logged in (
wrangler login) - Node.js 22+
- A Xero developer account and an app registered with OAuth 2.0
1. Fork and clone
git clone https://github.com/<your-username>/xero-mcp
cd xero-mcp
npm install
2. Create two KV namespaces
This worker uses two — one for per-client OAuth state (OAUTH_KV), one for your encrypted upstream Xero tokens (XERO_OAUTH_KV). Run both:
wrangler kv:namespace create OAUTH_KV
wrangler kv:namespace create XERO_OAUTH_KV
Each prints an id. Edit wrangler.jsonc and replace the two existing "id": "..." values under kv_namespaces with the ids wrangler just printed.
3. Register a Xero app
- Go to developer.xero.com → My Apps → New app
- App type: Web app
- Company URL: anything (e.g. your GitHub repo URL)
- Redirect URI: you'll come back and fix this after Step 5. For now use
http://localhost:8787/oauth/callback - Save → record the Client ID and Client Secret (in 1Password)
- Required Xero scopes (set on the app, not via UI — see Xero docs):
openid,profile,email,accounting.transactions,accounting.contacts,accounting.settings,offline_access
4. Set secrets
Generate a fresh approval code (this is what you paste at /authorize to mint a Claude bearer — never returned to clients):
openssl rand -base64 32
Store it in a password manager, then push all three secrets to Cloudflare:
wrangler secret put MCP_APPROVAL_CODE # paste the value from above
wrangler secret put XERO_CLIENT_ID # from Xero developer portal
wrangler secret put XERO_CLIENT_SECRET # from Xero developer portal
| Secret | Purpose |
|---|---|
MCP_APPROVAL_CODE | One-time code you paste at /authorize to mint a Claude bearer. Also used as the encryption secret for upstream Xero tokens at rest — rotating it invalidates stored tokens and forces clean Xero re-auth. |
XERO_CLIENT_ID | Your Xero app's Client ID. |
XERO_CLIENT_SECRET | Your Xero app's Client Secret. |
5. First deploy (to learn your worker URL)
npm run deploy
Wrangler prints your worker URL — something like https://xero-mcp.<your-account>.workers.dev. Save it.
6. Update WORKER_URL and Xero redirect URI
Two updates needed:
a) Edit wrangler.jsonc — under "vars", replace the existing WORKER_URL value with the URL from Step 5. This is used by the worker to advertise OAuth metadata and enforce redirect-URI matching.
b) In Xero developer portal, update the app's Redirect URI from the placeholder to <your-worker-url>/oauth/callback. Without this, Xero will reject the OAuth flow.
Then redeploy to push the updated WORKER_URL:
npm run deploy
7. Connect Xero (one time)
In your browser, visit <your-worker-url>/oauth/start. You'll be prompted to paste MCP_APPROVAL_CODE. After confirming, you're redirected to Xero to sign in and pick a tenant. After authorising, your encrypted upstream tokens land in XERO_OAUTH_KV. Refresh happens automatically thereafter.
8. Connect Claude.ai
- In Claude.ai, go to Settings → Integrations → Add MCP server
- Server URL:
<your-worker-url>/mcp - Claude.ai redirects you to your worker's
/authorizepage - Paste your
MCP_APPROVAL_CODEand confirm - You're connected — Claude now has the Xero tools available
Local development
wrangler dev
The worker runs at http://localhost:8787. You'll need .dev.vars (gitignored) with the same secrets above for local testing.
Endpoints
GET /.well-known/oauth-authorization-server— OAuth metadata (public)GET /.well-known/oauth-protected-resource— Resource metadata (public)GET /authorize— Approval-code paste page (public)POST /approve— Approval-code submission (rate-limited)POST /token— OAuth token exchange (rate-limited)POST /register— Dynamic client registration per RFC 7591 (rate-limited)GET /oauth/start— Begin Xero OAuth flow (operator-only, gated by MCP_APPROVAL_CODE)GET /oauth/callback— Xero OAuth redirect targetPOST /mcp— JSON-RPC tool dispatch (bearer-protected, rate-limited)
Stack
- Cloudflare Workers (compatibility_date
2025-04-28,nodejs_compat) - TypeScript (strict)
- Hono v4
- Zod v4
@bashco/mcp-toolkit— shared OAuth/crypto/rate-limit/dispatch plumbing
Continuous deployment
.github/workflows/deploy.yml runs wrangler deploy on every push to main. To enable on your fork, set two repository secrets:
CLOUDFLARE_API_TOKEN— create at dash.cloudflare.com/profile/api-tokens (use the "Edit Cloudflare Workers" template)CLOUDFLARE_ACCOUNT_ID— find at the bottom-right of your Cloudflare dashboard
Contributing
Issues and PRs welcome at github.com/doublebash/xero-mcp.
For changes to the underlying OAuth/crypto/rate-limit code, the toolkit lives at github.com/doublebash/mcp-toolkit — file issues there.
Security
Found a vulnerability? Please don't open a public issue. Open a private security advisory on GitHub.
License
MIT — Copyright (c) 2026 Bashar Basheer.