@crowdform/freeagent-mcp

An MCP server for the FreeAgent accounting API, so Claude can work with your accounts: browse invoices, bills, expenses, contacts and bank transactions, and help you reconcile unexplained bank activity.

Built against the FreeAgent API v2 docs (no OpenAPI spec exists — the API surface is indexed by hand under docs/api/).

Setup

Zero configuration — default OAuth app credentials are baked into the package, so install and connect:

claude mcp add freeagent -- npx -y @crowdform/freeagent-mcp

Or for Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "freeagent": { "command": "npx", "args": ["-y", "@crowdform/freeagent-mcp"] }
  }
}

Then ask Claude to connect to FreeAgent — it runs the connect_freeagent tool, which opens your browser to FreeAgent's approval page. The baked-in credentials only identify the app asking for access; nothing can touch your account until you click Approve on FreeAgent's own login page.

How auth & the token file work

Your login lives in ~/.freeagent-tokens.json (move it with FREEAGENT_TOKEN_PATH). When you approve access, the OAuth tokens and the organisation they belong to (company name, subdomain, currency) are saved there. On every startup the server reads that file and announces which organisation it is logged into, and check_auth_status reports it too — so Claude always knows whose books it's working on. To switch to a different FreeAgent account, run connect_freeagent with force=true (or delete the token file) and approve as the other account.

Tokens auto-refresh; you only need to authorize once (or again if the refresh token is revoked).

Using your own OAuth app (optional)

The baked-in defaults are used unless you override them: create an app at dev.freeagent.com (My Apps), add http://localhost:8462/callback to its OAuth redirect URIs, and set FREEAGENT_CLIENT_ID / FREEAGENT_CLIENT_SECRET in the environment (or a .env next to package.json when running from a checkout).

Set FREEAGENT_SANDBOX=true to point at the sandbox — this requires your own sandbox app; the baked-in app is production-only.

Authorizing from a terminal instead

From a checkout of this repo, npm run auth runs the same browser flow without an MCP session and saves tokens to the same place.

Authorizing without a localhost callback

If you can't (or don't want to) register the localhost redirect URI, get a refresh token any other way — e.g. the Google OAuth Playground (gear icon → "Use your own OAuth credentials", authorization endpoint https://api.freeagent.com/v2/approve_app, token endpoint https://api.freeagent.com/v2/token_endpoint) — then import it:

npm run auth -- --refresh-token <refresh_token>

This exchanges the refresh token for an access token, verifies it against the API, and saves both to the token file. FreeAgent refresh tokens are long-lived (valid until you revoke the app's access), and the server rotates/persists them automatically on every refresh — so this is a one-time step.

What it can do

• Company & reference data — company info, users, categories (with nominal codes), contacts
• Sales — list/get/create invoices, status transitions, credit notes, estimates
• Purchases — bills and expenses
• Banking — bank accounts, bank transactions (filter unexplained/manual/etc.)
• Reconciliation — create/update/delete bank transaction explanations (link to invoices, bills, transfers, or categorised money in/out), plus a matching helper that pairs unexplained transactions with open invoices/bills by amount, date and reference
• Reports — profit & loss, balance sheet, trial balance, VAT returns, general-ledger transactions

Notes

• FreeAgent identifies resources by URL (e.g. https://api.freeagent.com/v2/invoices/123). Tools accept either the full URL or the bare numeric id.
• List tools fetch up to 4 pages of 100 items and tell you when results were truncated.
• Rate limits (120/min) are handled with automatic backoff on 429s.
• The connected organisation (name, subdomain, currency) is saved alongside the tokens at authorization time, announced in the server's MCP instructions at startup, and returned by check_auth_status — so the assistant always knows whose books it is working on.

License & disclaimer

MIT — see LICENSE. This is an unofficial integration, not affiliated with or endorsed by FreeAgent Central Ltd. "FreeAgent" is a trademark of FreeAgent Central Ltd; all rights in the FreeAgent API and any data accessed through it remain with FreeAgent and the respective account holders. Your use of the API via this software is subject to FreeAgent's own terms.