Freeagent MCP Server

FreeAgent MCP Server

A Model Context Protocol server for FreeAgent accounting. Gives Claude (or any MCP client) the ability to reconcile bank transactions with receipts, claim expenses and mileage, raise and chase invoices, record supplier bills, log time against projects, and read the company's financial position.

What access this server requires

FreeAgent

The FreeAgent OAuth credentials grant full access to the connected FreeAgent account. This server uses that access to:

FreeAgent does not offer granular OAuth scopes — authorising an app grants access to all of the above.

Destructive operations. The delete tools are flagged destructiveHint: true so your MCP client can prompt before running them, as is freeagent_update_invoice_status (its mark_as_cancelled transition voids an issued invoice). The three whose loss is unrecoverable — freeagent_delete_expense, freeagent_delete_contact and freeagent_delete_project — additionally require confirm: true, so a client that auto-approves tool calls still cannot trigger them by accident. The server never deletes bank transactions, and never emails anything to your clients — status transitions change status only.

Outbound fetches. freeagent_explain_transaction, freeagent_create_expense, freeagent_update_expense, freeagent_create_bill and freeagent_update_bill each accept a fileUrl to download a receipt or invoice. That URL is treated as untrusted input: only http/https are allowed, hosts resolving to loopback, link-local, or private addresses are refused (on the initial request and on every redirect), and downloads are capped at 10 MB.

Local file reads. Those same tools accept a filePath, and the server reads that file from the host it runs on. The path must be absolute, and symlinks are resolved before the check. Over stdio the server runs as you, so this is no more access than the client already has. In HTTP mode the caller is remote, so local paths are refused outright unless you set FREEAGENT_ATTACHMENT_ROOTS to the directories that may be read (colon-separated); anything outside them is refused. Set it in stdio mode too if you want to bound what a prompt-injected model can attach.

Truncation. List tools page through results and report mayHaveMore; when true, any total they return covers only the records fetched and is named totalOutstandingForReturned. The freeagent_aged_debtors and freeagent_aged_creditors reports page to exhaustion and return complete: true — treat complete: false as an incomplete figure. Records whose due date is missing or unparseable are counted in a separate unknown_due_date bucket rather than being assumed not yet due.

Email and file sources (external — not provided by this server)

This server has no email tools. For receipt/invoice search to work automatically, connect one or more of the following MCP servers alongside this one:

• Gmail (e.g. mcp__claude_ai_Gmail) — personal email
• Microsoft 365 / Outlook (e.g. mcp__claude_ai_microsoft-365) — business email

When both are connected, Claude will search all of them automatically for matching receipts before asking you to provide a file manually.

---

Tools

Banking and expenses

Contacts, invoicing and bills

Time tracking

Projects

Reporting

---

Prerequisites

FreeAgent OAuth credentials

1. Log in to FreeAgent → Settings → Developer API.
2. Create an OAuth application. Set the redirect URI to http://localhost:8080/callback.
3. Note your Client ID and Client Secret.
4. Run the bundled auth command to complete the OAuth flow and save a refresh token to .mcp.json automatically:

npx @oxygenbubbles/freeagent-mcp-server auth

The command prompts for your Client ID and Client Secret, opens the FreeAgent authorization page in your browser, listens for the callback, exchanges the code for a long-lived refresh token, and writes everything to .mcp.json in the current directory. If .mcp.json already exists, it updates just the freeagent entry.

---

Installation

git clone https://github.com/OxygenBubbles/freeagent-mcp-server.git
cd freeagent-mcp-server
npm install
npm run build

---

Configuration

All settings are read from environment variables.

Required

Optional

Built-in vendor → category mappings

The server ships with mappings for common vendors, using FreeAgent's standard UK nominal codes:

• Web Hosting (268) — IONOS, AWS, Netlify, Vercel, Heroku, DigitalOcean, Cloudflare
• Computer Software (269) — OpenAI, Anthropic, GitHub, Stripe, Google, Microsoft, Zoom, Notion, Dropbox, Slack, Adobe, Fastmail, Mailchimp
• Accommodation and Meals (285) — Booking.com, Hotels.com, Premier Inn, Travelodge, Airbnb
• Travel (365) — Trainline, LNER, Uber

Check these against your own chart of accounts with freeagent_list_categories — nominal codes can be customised per account. Override or extend via VENDOR_CATEGORIES:

VENDOR_CATEGORIES='{"ACME CORP":"/v2/categories/285","NETFLIX":"/v2/categories/269"}'

---

Claude Desktop setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["/path/to/freeagent-mcp-server/dist/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "...",
        "FREEAGENT_CLIENT_SECRET": "...",
        "FREEAGENT_REFRESH_TOKEN": "..."
      }
    }
  }
}

---

Usage examples

List my unexplained Starling transactions for April 2026

Approve explanation 12345678 and attach the receipt at ~/Downloads/invoice.pdf

Create an expense for the £22.80 IONOS charge on 3 April, rebilled to the Example Client project at cost — the receipt is at ~/Desktop/ionos.png

That IONOS expense should be Reverse Charge, not UK/Non-EC — fix it

Log 24 miles for a client visit from the office to a customer site on 10 April

Add a line to draft invoice 4471 for 2 days' consultancy at £650

Which April expenses are tagged to a project but not set to rebill?

Show me everything queued to bill on to Example Client that isn't on an invoice yet

---

Mileage rates

Mileage is a special FreeAgent category: you submit the miles and vehicle type, and FreeAgent calculates the claim value from the mileage rate configured on the account. That figure is what appears in your accounts and HMRC reporting, so the server does not attempt to override it.

The estimate returned alongside the filed amount uses that same rate: the server reads GET /v2/expenses/mileage_settings and applies the band published for the journey's date and vehicle. The response records where the rate came from in estimateSource:

The last two are fallbacks, and the response says so in notes. When the estimate and the filed amount still differ, that is worth a look:

FreeAgent filed £46.20 using the mileage rate configured on the account; the estimate from 84 miles @ 45p/mile (FreeAgent mileage settings) was £37.80.

HMRC's approved rates are 45p/mile for the first 10,000 business miles in the tax year and 25p above it, and anything paid above the approved rate is a taxable benefit.

To reclaim the VAT on the fuel element, pass engineType and engineSize (and haveVatReceipt) — FreeAgent cannot calculate it without them.

---

Development

npm run dev        # watch mode (tsx)
npm run build      # compile TypeScript → dist/
npm start          # run compiled server
npm test           # run unit tests once
npm run test:watch # watch mode for tests

---

Claude Code setup

Create .mcp.json in your project directory (or ~/.mcp.json for global access):

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["/path/to/freeagent-mcp-server/dist/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "...",
        "FREEAGENT_CLIENT_SECRET": "...",
        "FREEAGENT_REFRESH_TOKEN": "..."
      }
    }
  }
}

---

HTTP mode

Set PORT to run as an HTTP server (for webhooks, iPhone Shortcuts, Power Automate):

PORT=3000 AUTH_TOKEN=a-long-random-string node dist/index.js

Always set AUTH_TOKEN when exposing HTTP mode — every request must include Authorization: Bearer <AUTH_TOKEN> or it is rejected with 401. Without AUTH_TOKEN the server starts anyway but prints a warning to stderr and accepts all requests; only do that on a trusted loopback interface.

---

Security

• Credentials are environment variables, never in code
• FreeAgent tokens are cached in memory and refreshed automatically
• Transactions are never approved without a confirmed receipt or explicit instruction
• The server never creates new categories — only selects from existing ones
• Receipt URLs are fetched through an SSRF guard: the address validated is the address dialled, every redirect hop is re-checked, proxies are bypassed and downloads are size-capped
• Local receipt paths must be absolute and are resolved through symlinks before use; in HTTP mode they are refused unless FREEAGENT_ATTACHMENT_ROOTS names the directories that may be read
• The three deletes whose loss is unrecoverable — expenses, contacts and projects — require confirm: true in addition to the client's own prompt
• .mcp.json is excluded from git via .gitignore

---

Licence

MIT