freeagent-mcp

An MCP server for the FreeAgent accounting API (v2). It lets Claude, Cursor or any other MCP client read your FreeAgent data, and optionally change it.

It runs on your own computer over stdio. There is no hosted service and no build step.

Compatibility

Check your Node version with node -v. Install Node 24 from https://nodejs.org or with nvm install 24.

Related MCP server: FreeAgent MCP Server

1. Create your own FreeAgent app

Every person creates their own app. Do not share a client secret.

1. Sign in at https://dev.freeagent.com with your FreeAgent login.

2. Go to My Apps, then Create New App.

3. Fill in:

   • Name: anything, for example My FreeAgent MCP

   • OAuth Redirect URIs: http://localhost:8765/callback

4. Save. Copy the OAuth identifier and the secret. FreeAgent shows the secret only once.

To test without real data, also create a sandbox company at https://signup.sandbox.freeagent.com/signup and set FREEAGENT_SANDBOX=1 (see below).

2. Install

git clone https://github.com/DevGuildLtd/freeagent-mcp.git
cd freeagent-mcp
npm ci

3. Save the app credentials

Create ~/.config/freeagent-mcp/app.json:

{
  "clientId": "YOUR_OAUTH_IDENTIFIER",
  "clientSecret": "YOUR_SECRET",
  "redirectUri": "http://localhost:8765/callback"
}

On macOS or Linux, make it private:

chmod 700 ~/.config/freeagent-mcp && chmod 600 ~/.config/freeagent-mcp/app.json

On Windows the folder is %USERPROFILE%\.config\freeagent-mcp.

Instead of the file you can set FREEAGENT_CLIENT_ID and FREEAGENT_CLIENT_SECRET in the client config (see step 4). This works well with a password manager, for example op run from 1Password.

4. Add it to your MCP client

Use the full path to your clone in place of /path/to/freeagent-mcp.

Claude Code

claude mcp add freeagent -s user -- node /path/to/freeagent-mcp/src/index.ts

With writes turned on:

claude mcp add freeagent -s user -e FREEAGENT_ALLOW_WRITES=1 -- node /path/to/freeagent-mcp/src/index.ts

Claude Desktop, Cursor, VS Code and others

Add this to the client's MCP config file. For Claude Desktop that is claude_desktop_config.json (Settings, Developer, Edit Config). For Cursor it is ~/.cursor/mcp.json.

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["/path/to/freeagent-mcp/src/index.ts"],
      "env": {
        "FREEAGENT_ALLOW_WRITES": "0"
      }
    }
  }
}

VS Code uses "servers" in place of "mcpServers" in .vscode/mcp.json.

If the client cannot find node (common with nvm and Claude Desktop), put the full path from which node in command.

5. First use and login

Ask your client something like "list my open FreeAgent invoices".

The first FreeAgent call opens the FreeAgent approval page in your browser. Sign in if you need to and click Approve. The call then goes on. You have 3 minutes. If the browser does not open, the tool error shows the link.

By default the tokens stay in memory only. Nothing goes to disk, and you approve again in each new session. To stay logged in across sessions:

npm run login

and set FREEAGENT_TOKEN_STORE=file in the client config. Tokens then go to ~/.config/freeagent-mcp/tokens.json and refresh on their own. Any program running as your user can read that file.

Tools

API reference: https://dev.freeagent.com/docs

Settings

All settings are environment variables.

Security

• The server acts as the FreeAgent user who approves it, with that user's full permission level. FreeAgent apps have no scopes. For a safer setup, approve with a FreeAgent user that has a lower permission level.

• Writes are off by default. With writes on, an agent can create, change and delete records, and some actions cannot be undone, for example filing a VAT return or emailing an invoice.

• To cut off access, remove the app from your FreeAgent account settings, or revoke the secret on the developer portal.

Troubleshooting

Development

npm run typecheck
FREEAGENT_SANDBOX=1 npm start

License

MIT. See LICENSE.