{"id":49418374,"url":"https://github.com/groupthink-dev/xero-blade-mcp","last_synced_at":"2026-04-29T04:12:40.480Z","repository":{"id":348520442,"uuid":"1198417650","full_name":"Groupthink-dev/xero-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-21T09:56:38.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T11:40:33.962Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T12:06:18.000Z","updated_at":"2026-04-21T09:56:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/xero-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/xero-blade-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/xero-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fxero-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fxero-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fxero-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fxero-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/xero-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fxero-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32410084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T03:46:11.172Z","status":"ssl_error","status_checked_at":"2026-04-29T03:37:55.317Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:12:31.001Z","updated_at":"2026-04-29T04:12:40.469Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xero-blade-mcp\n\nXero Accounting + Payroll AU MCP server for Claude and other LLM agents. Token-efficient, security-first, Sidereal-native.\n\n53 tools covering contacts, invoices, bills, bank transactions, payments, credit notes, purchase orders, quotes, manual journals, chart of accounts, financial reports, tax rates, currencies, tracking categories, payroll employees, timesheets, payslips, and webhook verification.\n\n## Why another Xero MCP?\n\nThe [official Xero MCP](https://github.com/XeroAPI/xero-mcp-server) is a raw API passthrough. It returns complete JSON payloads (800+ tokens per list response), has no write protection, no credential scrubbing, and no published test suite. Community alternatives are either expense-only, read-only (SQL), or limited to 4-16 tools.\n\nxero-blade-mcp is purpose-built for LLM agents operating on financial data:\n\n- **SecOps** -- Mandatory write gating, confirm gate for destructive operations (void, delete, archive), credential scrubbing in all error paths, OAuth2 token auto-refresh, in-memory-only tokens for client_credentials mode (no secrets written to disk)\n- **Token efficiency** -- Pipe-delimited lists, field selection, human-readable money (A$150.00 AUD), null-field omission, date formatting, pagination hints -- not raw JSON dumps\n- **Sidereal ecosystem** -- `accounting-v1` contract, plugin manifest, webhook HMAC-SHA256 verification for dispatch integration, HTTP transport mode for daemon routing\n\n## Comparison\n\n| Capability | xero-blade-mcp | XeroAPI/xero-mcp-server | john-zhang-dev/xero-mcp |\n|---|---|---|---|\n| Tools | 53 | 50+ | 16 |\n| Token-efficient responses | Pipe-delimited, field selection, summarised | Raw JSON (full objects) | Raw JSON |\n| Write gating | Per-operation env var gate | None | None |\n| Destructive op confirmation | `confirm=true` required for void/delete/archive | None | None |\n| Credential scrubbing | JWT, Bearer, hex token scrubbing | None | None |\n| Rate limiting | Built-in (60/min, 5 concurrent, 429 retry) | None | None |\n| Payroll AU | Employees, timesheets, payslips | Claimed | None |\n| Webhook HMAC verification | Built-in tool (HMAC-SHA256) | None | None |\n| Reports | P\u0026L, Balance Sheet, Trial Balance, Aged AR/AP | Yes | Limited |\n| Multi-tenant | XERO_TENANT_ID + discovery tool | Yes | Yes |\n| Auth modes | Custom Connection + PKCE + static token | Custom Connection + Bearer | OAuth2 |\n| Tests | 414 unit tests | Undisclosed | Partial |\n| Sidereal integration | accounting-v1 contract, plugin manifest | None | None |\n| Runtime | Python (uv) | Node.js (npx) | Node.js |\n\n### Token efficiency: before and after\n\n**XeroAPI/xero-mcp-server** (raw JSON, ~1200 tokens):\n```json\n{\"Invoices\":[{\"InvoiceID\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"InvoiceNumber\":\"INV-0001\",\"Type\":\"ACCREC\",\"Contact\":{\"ContactID\":\"f1e2d3c4-b5a6-7890-fedc-ba0987654321\",\"Name\":\"Acme Corp\",\"ContactStatus\":\"ACTIVE\",\"EmailAddress\":\"billing@acme.com\",\"IsCustomer\":true,\"IsSupplier\":false},\"DateString\":\"2026-03-15T00:00:00\",\"DueDateString\":\"2026-04-14T00:00:00\",\"Status\":\"AUTHORISED\",\"SubTotal\":1500.00,\"TotalTax\":150.00,\"Total\":1650.00,\"AmountDue\":1650.00,\"AmountPaid\":0.00,\"CurrencyCode\":\"AUD\",\"LineItems\":[{\"Description\":\"Consulting services - March 2026\",\"Quantity\":10.0,\"UnitAmount\":150.00,\"LineAmount\":1500.00,\"AccountCode\":\"200\",\"TaxType\":\"OUTPUT\"}]}]}\n```\n\n**xero-blade-mcp** (pipe-delimited, ~60 tokens):\n```\nINV-0001 | Acme Corp | AUTHORISED | A$1,650.00 AUD | 2026-04-14 | due=A$1,650.00 AUD\n```\n\n**16x fewer tokens** for the same information. For a P\u0026L report the savings are even larger -- structured table output vs nested JSON arrays.\n\n## Quick start\n\n```bash\n# Install\nuv tool install xero-blade-mcp\n\n# Configure (Custom Connection -- recommended)\nexport XERO_CLIENT_ID=\"your_client_id\"\nexport XERO_CLIENT_SECRET=\"your_client_secret\"\nexport XERO_TENANT_ID=\"your_tenant_id\"\n\n# Run\nxero-blade-mcp\n```\n\n### Claude Desktop / Claude Code\n\n```json\n{\n  \"mcpServers\": {\n    \"xero\": {\n      \"command\": \"uvx\",\n      \"args\": [\"xero-blade-mcp\"],\n      \"env\": {\n        \"XERO_CLIENT_ID\": \"your_client_id\",\n        \"XERO_CLIENT_SECRET\": \"your_client_secret\",\n        \"XERO_TENANT_ID\": \"your_tenant_id\"\n      }\n    }\n  }\n}\n```\n\n### HTTP transport (remote/tunnel access)\n\n```bash\nexport XERO_MCP_TRANSPORT=\"http\"\nexport XERO_MCP_HOST=\"127.0.0.1\"\nexport XERO_MCP_PORT=\"8770\"\nexport XERO_MCP_API_TOKEN=\"your-bearer-token\"  # optional, enables auth\nxero-blade-mcp\n```\n\n## Authentication\n\nThree modes, in priority order:\n\n| Mode | Env Vars | Use Case |\n|---|---|---|\n| **Static token** | `XERO_ACCESS_TOKEN` | Testing, short-lived (30 min expiry) |\n| **Custom Connection** | `XERO_CLIENT_ID` + `XERO_CLIENT_SECRET` | Production MCP (recommended, auto-refresh) |\n| **Stored tokens** | `XERO_CLIENT_ID` | After initial PKCE flow (tokens persisted to `~/.xero-blade-mcp/tokens.json` only when refresh_token is present) |\n\n### Setting up a Custom Connection\n\n1. Go to [developer.xero.com](https://developer.xero.com) and create a new app\n2. Select \"Custom connection\" as the app type\n3. Select the organisation to connect\n4. Grant scopes: `accounting.transactions`, `accounting.contacts`, `accounting.settings`, `accounting.reports.read`, `payroll.employees`, `payroll.timesheets`, `payroll.payslips`\n5. Note the Client ID and Client Secret\n6. Use `xero_connections` tool to find your Tenant ID\n\n## Security model\n\n### Write gate\n\nAll create, update, delete, and void operations require `XERO_WRITE_ENABLED=true`. Without it, the server is read-only.\n\n### Confirm gate\n\nDestructive operations that are difficult to reverse require `confirm=true` as a parameter:\n\n| Operation | Gate |\n|---|---|\n| `xero_archive_contact` | write + confirm |\n| `xero_void_invoice` | write + confirm |\n| `xero_void_bill` | write + confirm |\n| `xero_delete_payment` | write + confirm |\n| `xero_void_credit_note` | write + confirm |\n| `xero_approve_timesheet` | write + confirm |\n\n### Credential scrubbing\n\nAll error messages are scrubbed of:\n- JWT tokens (`eyJ...` patterns)\n- Bearer authorization headers\n- Long hexadecimal strings (OAuth tokens, secrets)\n\n### Rate limiting\n\nBuilt-in rate limiter respects Xero's API limits:\n- 60 API calls per minute per tenant\n- 5 concurrent requests\n- Automatic retry on 429 with Retry-After header\n\n## Configuration\n\n| Variable | Required | Description |\n|---|---|---|\n| `XERO_CLIENT_ID` | Yes* | OAuth2 client ID |\n| `XERO_CLIENT_SECRET` | Yes* | OAuth2 client secret (Custom Connection) |\n| `XERO_TENANT_ID` | Recommended | Active organisation tenant ID |\n| `XERO_ACCESS_TOKEN` | No | Pre-obtained access token (overrides OAuth) |\n| `XERO_WRITE_ENABLED` | No | Set to `true` to enable write operations |\n| `XERO_WEBHOOK_KEY` | No | Webhook signing key for HMAC verification |\n| `XERO_MCP_TRANSPORT` | No | `stdio` (default) or `http` |\n| `XERO_MCP_HOST` | No | HTTP host (default: `127.0.0.1`) |\n| `XERO_MCP_PORT` | No | HTTP port (default: `8770`) |\n| `XERO_MCP_API_TOKEN` | No | Bearer token for HTTP transport auth |\n\n\\* Either `XERO_CLIENT_ID` + `XERO_CLIENT_SECRET` or `XERO_ACCESS_TOKEN` required.\n\n## Tools\n\n### Meta (3 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_info` | Connection status, active tenant, config | R |\n| `xero_connections` | List connected tenants/organisations | R |\n| `xero_organisation` | Organisation details, currency, tax settings | R |\n\n### Contacts (5 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_contacts` | List contacts with search, status filter | R |\n| `xero_contact` | Contact detail with field selection | R |\n| `xero_create_contact` | Create contact | W |\n| `xero_update_contact` | Update contact fields | W |\n| `xero_archive_contact` | Archive contact (confirm required) | W+C |\n\n### Invoices (6 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_invoices` | List sales invoices with filters | R |\n| `xero_invoice` | Invoice detail with line items, payments | R |\n| `xero_create_invoice` | Create sales invoice | W |\n| `xero_update_invoice` | Update draft/submitted invoice | W |\n| `xero_void_invoice` | Void invoice (confirm required) | W+C |\n| `xero_email_invoice` | Email invoice to contact | W |\n\n### Bills (4 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_bills` | List purchase bills | R |\n| `xero_bill` | Bill detail with line items | R |\n| `xero_create_bill` | Create purchase bill | W |\n| `xero_void_bill` | Void bill (confirm required) | W+C |\n\n### Bank Transactions (3 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_bank_transactions` | List bank transactions | R |\n| `xero_bank_transaction` | Transaction detail | R |\n| `xero_create_bank_transaction` | Create spend/receive transaction | W |\n\n### Payments (4 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_payments` | List payments | R |\n| `xero_payment` | Payment detail | R |\n| `xero_create_payment` | Record payment against invoice/bill | W |\n| `xero_delete_payment` | Delete payment (confirm required) | W+C |\n\n### Credit Notes (3 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_credit_notes` | List credit notes | R |\n| `xero_create_credit_note` | Create credit note | W |\n| `xero_void_credit_note` | Void credit note (confirm required) | W+C |\n\n### Purchase Orders (2 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_purchase_orders` | List purchase orders | R |\n| `xero_create_purchase_order` | Create purchase order | W |\n\n### Quotes (2 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_quotes` | List quotes | R |\n| `xero_create_quote` | Create quote | W |\n\n### Accounts (2 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_accounts` | Chart of accounts with type/class filter | R |\n| `xero_account` | Account detail | R |\n\n### Manual Journals (1 tool)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_manual_journals` | List manual journal entries | R |\n\n### Reports (5 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_profit_loss` | P\u0026L report with date range, periods | R |\n| `xero_balance_sheet` | Balance sheet as at date | R |\n| `xero_trial_balance` | Trial balance as at date | R |\n| `xero_aged_receivables` | Aged receivables with breakdown | R |\n| `xero_aged_payables` | Aged payables with breakdown | R |\n\n### Reference Data (4 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_tax_rates` | Tax rates and effective percentages | R |\n| `xero_currencies` | Active currencies | R |\n| `xero_tracking_categories` | Tracking categories and options | R |\n| `xero_branding_themes` | Branding themes for documents | R |\n\n### Payroll AU (8 tools)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_employees` | List payroll employees | R |\n| `xero_employee` | Employee detail (tax, super, leave) | R |\n| `xero_timesheets` | List timesheets | R |\n| `xero_timesheet` | Timesheet detail with lines | R |\n| `xero_create_timesheet` | Create timesheet | W |\n| `xero_approve_timesheet` | Approve timesheet (confirm required) | W+C |\n| `xero_payslips` | List payslips for a pay run | R |\n| `xero_payslip` | Payslip detail (earnings, deductions, super) | R |\n\n### Webhooks (1 tool)\n\n| Tool | Description | R/W |\n|---|---|---|\n| `xero_verify_webhook` | HMAC-SHA256 signature verification | R |\n\n## Development\n\n```bash\n# Setup\ngit clone https://github.com/groupthink-dev/xero-blade-mcp.git\ncd xero-blade-mcp\nmake install-dev\n\n# Test\nmake test           # 414 unit tests\nmake test-cov       # with coverage report\n\n# Quality\nmake lint           # ruff linter\nmake format         # ruff formatter\nmake type-check     # mypy\nmake check          # all of the above\n```\n\n## Sidereal integration\n\nImplements the `accounting-v1` service contract. Registered in the [Sidereal Plugin Registry](https://github.com/groupthink-dev/sidereal-plugin-registry).\n\n```yaml\n# sidereal-plugin.yaml\ncontract: accounting-v1\ntier: certified\ntools: 53\n```\n\n## Xero API scope requirements\n\n| Scope | APIs Covered |\n|---|---|\n| `accounting.transactions` | Invoices, Bills, Bank Transactions, Payments, Credit Notes, POs, Quotes |\n| `accounting.contacts` | Contacts |\n| `accounting.settings` | Accounts, Tax Rates, Currencies, Tracking, Branding |\n| `accounting.reports.read` | P\u0026L, Balance Sheet, Trial Balance, Aged AR/AP |\n| `payroll.employees` | Employees |\n| `payroll.timesheets` | Timesheets |\n| `payroll.payslips` | Pay Runs, Payslips |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fxero-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fxero-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fxero-blade-mcp/lists"}