#FreeAgent MCP

[!WARNING] This project is 100% vibe coded. I haven't tested everything or looked at the code. Things might not work. Use at your own risk.

A local, read-only MCP server that exposes FreeAgent accounting data to AI clients (Claude Desktop, the ChatGPT desktop app, or anything else that speaks MCP over stdio), so you can ask questions like "why is there £4,200 sitting in nominal code 907?" and have the model drill down into the underlying transactions.

Read-only is enforced at the HTTP client layer: the client exposes a get() method and nothing else — any attempt to call another verb throws. Every tool is annotated read-only and idempotent. There is no code path that can modify accounting data, and the VAT filing / MTD submission endpoints are not touched at all.

The server is built on Laravel, so if you don't have PHP set up locally (with Herd or similar) it might not be that useful to you. That said, you could use something like Laravel Sail to run it in a Docker container instead.

#Setup

Install and migrate:

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate

Register an OAuth app on the FreeAgent Developer Dashboard, giving it http://localhost as a redirect URI — FreeAgent only accepts redirect URIs that exactly match one registered on the app. Then add the keys to .env:
```
FREEAGENT_CLIENT_ID=your-client-id
FREEAGENT_CLIENT_SECRET=your-client-secret
FREEAGENT_SANDBOX=false
```
If your app already has a different redirect URI registered, set FREEAGENT_REDIRECT_URI to that value instead of registering a new one.
Authenticate:
```
php artisan freeagent:auth
```
Open the printed URL, approve the app, then paste the URL you're redirected to back into the terminal. Tokens are stored (encrypted) in SQLite and refreshed automatically from then on.
Check it worked:
```
php artisan freeagent:status
```

#Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
    "mcpServers": {
        "freeagent": {
            "command": "php",
            "args": ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
        }
    }
}

#Claude Code

Add the server from any project (--scope user makes it available everywhere, drop it to register for the current project only):

claude mcp add freeagent --scope user -- php /absolute/path/to/freeagent-mcp/artisan mcp:start freeagent

Or add it to a project's .mcp.json by hand:

{
    "mcpServers": {
        "freeagent": {
            "command": "php",
            "args": ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
        }
    }
}

Check it's connected with /mcp inside a session.

#ChatGPT desktop app

Add to ~/.codex/config.toml (or via Settings → MCP servers → Add server → STDIO):

[mcp_servers.freeagent]
command = "php"
args = ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
cwd = "/absolute/path/to/freeagent-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

writes mode auto-approves read-only tools and prompts for anything else — since every tool here is marked read-only, that means no prompts, with a hard backstop. Note this only works in the ChatGPT desktop app; ChatGPT web won't see it.

#Tools

Tool	What it does
`get_company_context`	Company details, fiscal year end, currency, users and the FreeAgent subdomain. Cheap orientation call.
`list_categories`	The full chart of accounts with nominal codes, including bank account and user sub-accounts. Optional search.
`get_balance_sheet`	Balance sheet as at a date, or the opening balances.
`get_trial_balance`	Trial balance summary for a date range, or the opening balances.
`get_profit_and_loss`	P&L summary for a date range: income, expenses, deductions, retained profit.
`get_cashflow`	Cash in/out by month with the net balance.
`explain_category`	Every ledger transaction that hit a nominal code in a range, with source documents, deep links and a running total — reconciled against the trial balance.
`search_transactions`	Free-text search across ledger transactions with date, amount, bank account and nominal code filters.
`list_records`	Generic list endpoint for 35 other read-only resources (banking, documents, contacts, projects, tax returns, assets, payroll, time).
`get_record`	Full detail of a single record by resource and id.

#Other commands

php artisan freeagent:status       # auth state + connected company
php artisan freeagent:clear-cache  # drop cached API responses
php artisan mcp:inspector freeagent # debug the server interactively

Responses are cached in the database (an hour for reports and reference data, 15 minutes for transactions), so restarting the MCP client doesn't burn through FreeAgent's rate limits (120 requests/minute, 3,600/hour).

Auf iPhone/iPad installieren

Freeagent Mcp