freeagent-mcp-server

An MCP server that gives Claude, Codex, Cursor, VS Code, Gemini CLI or any other MCP client the FreeAgent accounting API: 76 tools for invoices, expenses, bills, contacts, projects, timeslips, banking, estimates, credit notes and the accounting reports.

Text that comes back from FreeAgent, such as a bank transaction’s reference, can be written by someone outside your business, so the server assumes it may carry instructions aimed at the model. Tools that could hand over account access or send data out of the account are off by default, every tool says whether it reads, writes or deletes, and receipts are only read from one folder you choose.

Contents

• How it fits together
• Quick start
• What it can do
• Settings
• Development
• Documentation
• Links

How it fits together

Claude, Codex, Cursor, VS Code, … ──stdio──▶ freeagent-mcp-server (Node.js, on your machine)
                                                   ├─ 76 tools; sensitive ones only with FREEAGENT_ENABLE_SENSITIVE_TOOLS
                                                   ├─ OAuth2 tokens in ~/.freeagent-mcp/tokens.json, refreshed automatically
                                                   ├─ receipts read from FREEAGENT_ATTACHMENTS_DIR only
                                                   └──HTTPS, your bearer token──▶ api.freeagent.com/v2 (or the sandbox)

The server runs locally, started by your MCP client, and talks to nothing but FreeAgent’s API. That’s also why ChatGPT and Grok can’t use it yet: they only connect to MCP servers hosted on the internet (details).

Quick start

Node.js 24 or later, and a FreeAgent account. New to this? Follow the step-by-step guide: docs/setup.md.

1. Get a client ID and secret. In the FreeAgent Developer Dashboard, create an app with the redirect URI http://localhost:3456/callback. Its OAuth identifier is your client ID and its OAuth secret is your client secret.

2. Connect your FreeAgent account, once, in a terminal. Your browser opens FreeAgent: log in and approve the app.

   export FREEAGENT_CLIENT_ID="your_client_id"
   export FREEAGENT_CLIENT_SECRET="your_client_secret"
   npx freeagent-mcp-server auth
   

3. Add it to Claude: claude_desktop_config.json for Claude Desktop and Cowork (on macOS in ~/Library/Application Support/Claude/), .mcp.json for Claude Code. Then restart the client. Codex CLI, Cursor, VS Code, Windsurf and Gemini CLI take the same command and credentials in their own config file: docs/configuration.md.

   {
     "mcpServers": {
       "freeagent": {
         "command": "npx",
         "args": ["-y", "freeagent-mcp-server"],
         "env": {
           "FREEAGENT_CLIENT_ID": "your_client_id",
           "FREEAGENT_CLIENT_SECRET": "your_client_secret"
         }
       }
     }
   }
   

Check it works by asking “Show me my FreeAgent company details”, then try “List all overdue invoices”. Every setting, the sandbox, and installing globally or from source: docs/configuration.md.

What it can do

List tools page through results (page, per_page up to 100). Every tool, its endpoint and example prompts: docs/tools.md.

Settings

Why the sensitive tools are off and how attachments are confined: docs/security.md. Something not working: docs/troubleshooting.md.

Development

npm install
npm run lint && npm run type-check && npm test && npm run build

CI runs the same on Node 24 for every pull request (test (24), required on main). Commits and PR titles are conventional (feat:, fix:, docs: and so on); main squash-merges, so the PR title is the commit. Releases are opened by hand with /release, and merging the release PR publishes to npm (RELEASING.md). AGENTS.md has the rules that don’t bend; what’s where and adding a tool: docs/development.md.

Documentation

The whole map is docs/README.md.

Links

• npm package
• FreeAgent API docs and quick start
• Issues

License

MIT