convez.ai
MCP Server
doublebash

xero-mcp

doublebash/xero-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Claude.ai ↔ your worker — standard MCP OAuth 2.0 + PKCE flow. Each Claude client gets a unique bearer token; your MCP_APPROVAL_CODE is what you paste at /authorize once to mint that bearer.
  2. Your worker ↔ Xero — proxied OAuth. You authorise Xero once by visiting /oauth/start on your deployed worker; tokens are stored encrypted at rest in Cloudflare KV. Refresh is automatic.

Setup — deploy your own copy

Prerequisites

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

  1. Go to developer.xero.com → My Apps → New app
  2. App type: Web app
  3. Company URL: anything (e.g. your GitHub repo URL)
  4. Redirect URI: you'll come back and fix this after Step 5. For now use http://localhost:8787/oauth/callback
  5. Save → record the Client ID and Client Secret (in 1Password)
  6. 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
SecretPurpose
MCP_APPROVAL_CODEOne-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_IDYour Xero app's Client ID.
XERO_CLIENT_SECRETYour 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

  1. In Claude.ai, go to Settings → Integrations → Add MCP server
  2. Server URL: <your-worker-url>/mcp
  3. Claude.ai redirects you to your worker's /authorize page
  4. Paste your MCP_APPROVAL_CODE and confirm
  5. 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 target
  • POST /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.

Ver o original no GitHub

Bom para

Relacionados