FreeAgent MCP Server
The FreeAgent MCP Server connects AI assistants to FreeAgent accounting, enabling automated bookkeeping, invoicing, expense management, and financial reporting. Key capabilities:
Banking & Reconciliation: List bank accounts; list, explain, and approve transactions; attach receipts via URL, file, or base64.
Expenses & Mileage: Create expense claims (with receipt, project tagging, auto-match); create mileage claims with HMRC-based estimates; browse expense categories.
Contacts & Invoicing: List and create contacts; list, create, update status (sent/draft/cancelled), and delete invoices.
Bills: List, create (with optional PDF attachment), and delete supplier bills.
Time Tracking: List projects, create tasks, log and manage timeslips.
Financial Reporting: Profit & Loss, Trial Balance, Aged Debtors, Aged Creditors, Tax Timeline, Company Summary.
Extras: Receipt search integration (Gmail/Outlook), custom vendor-to-category mappings, configurable mileage rates, distance API support, flexible deployment (stdio or HTTP with auth).
Provides automatic driving distance calculation between two locations for mileage expense logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreeAgent MCP Server show me my unexplained bank transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Action | Tools that use it |
Read bank accounts |
|
Read bank transactions and explanations |
|
Update transaction explanations (category, description, project, rebilling, VAT, approval, attachments) |
|
Read, create, amend and delete expense claims |
|
Read the chart of accounts |
|
Read, create, amend and delete projects |
|
Read, create, amend and delete contacts |
|
Read, raise, edit and change the status of invoices |
|
Read, record and amend supplier bills |
|
Read, log and amend time against project tasks |
|
Read accounting reports |
|
Delete expenses, invoices, bills, contacts, projects, tasks and timeslips |
|
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 emailMicrosoft 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.
Related MCP server: freee MCP Server
Tools
Banking and expenses
Tool | Description |
| List all bank accounts and their IDs |
| List transactions (unexplained / explained / all / marked_for_review) with date filters |
| Update, approve, rebill or attach a receipt to a transaction explanation |
| List the full chart of accounts — all four category groups |
| List expense claims by date or project, with |
| Create an expense claim with optional receipt (local path, URL or base64), project tag with rebill type/factor, EC VAT status and bank-transaction auto-matching |
| Update an existing expense — attach or replace the receipt, set the rebill treatment, retag project/category, correct date, amount or VAT |
| Create a mileage claim with engine type/size for fuel VAT, optionally rebilled to a project; the rate comes from the account's own mileage settings |
| Delete an expense filed in error (needs |
Contacts, invoicing and bills
Tool | Description |
| List clients and suppliers, with an optional name/email filter |
| Create a client or supplier, with VAT registration number and default payment terms |
| Update a contact, add its VAT number, or hide it ( |
| Delete a contact (needs |
| List invoices by view ( |
| Fetch one invoice in full, including line items |
| Raise an invoice with line items and EC VAT status — always created as a draft |
| Edit a draft invoice — dates, project, VAT status, discount, and add/edit/remove line items |
| Mark an invoice as sent, draft, scheduled or cancelled (no email is sent) |
| Delete an invoice |
| List supplier bills with the total outstanding |
| Fetch one bill in full, including line items and their URLs (needed to edit lines) |
| Record a supplier bill, with optional invoice attachment (local path, URL or base64), EC VAT status, project allocation and rebill treatment |
| Update a bill — reference, dates, VAT status, project, rebill treatment, attachment and line items |
| Delete a bill |
Time tracking
Tool | Description |
| List project tasks (time is always logged against a task) |
| Create a project task with its billing rate |
| Rename a task, change its billing rate, or close it ( |
| Delete a task with no time logged against it |
| List logged time for a date range, with totals per project; |
| Log time against a project task |
| Correct a timeslip's hours, date, task or comment |
| Delete a timeslip |
Projects
Tool | Description |
| List projects, for tagging expenses, invoices, bills and time |
| Create a project against a client contact — only contact and name are required |
| Rename, rebudget, change billing rate or close a project |
| Delete a project with nothing booked against it (needs |
Reporting
Tool | Description |
| Income, expenses, operating profit, corporation tax estimate and retained profit |
| Balance on every nominal account |
| Unpaid customer invoices bucketed by age (not yet due, 1–30, 31–60, 61–90, 90+ days) |
| Unpaid supplier bills bucketed by age |
| Upcoming VAT, corporation tax and Companies House deadlines with amounts due |
| Company details, VAT registration and accounting year end |
Prerequisites
FreeAgent OAuth credentials
Log in to FreeAgent → Settings → Developer API.
Create an OAuth application. Set the redirect URI to
http://localhost:8080/callback.Note your Client ID and Client Secret.
Run the bundled auth command to complete the OAuth flow and save a refresh token to
.mcp.jsonautomatically:
npx @oxygenbubbles/freeagent-mcp-server authThe 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 buildConfiguration
All settings are read from environment variables.
Required
Variable | Description |
| OAuth client ID |
| OAuth client secret |
| Long-lived refresh token |
Optional
Variable | Description |
| JSON object extending the built-in vendor → category mapping (see below) |
| FreeAgent category URL for mileage expenses (default |
| Fallback pence-per-mile rate for the estimate, used only when FreeAgent's own mileage settings cannot be read |
| HMRC high-band rate in pence, used as a last-resort fallback (default |
| HMRC low-band rate in pence, used as a last-resort fallback (default |
| Miles per tax year before the low band kicks in (default |
| OpenRouteService API key for drive-distance lookups |
| Google Maps API key for drive-distance lookups (alternative to ORS) |
| If set, serves over HTTP on this port instead of stdio |
| Colon-separated directories that |
| Bearer token required on every HTTP request. Strongly recommended whenever |
| Set to |
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 yetMileage 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:
| Meaning |
| The account's own published rate — the normal case |
| A |
| Settings could not be read; the environment variable was used |
| Settings could not be read and no override was set; the built-in HMRC bands were used |
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 testsClaude 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.jsAlways 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_ROOTSnames the directories that may be readThe three deletes whose loss is unrecoverable — expenses, contacts and projects — require
confirm: truein addition to the client's own prompt.mcp.jsonis excluded from git via.gitignore
Licence
MIT
Available Tools
28 toolsfreeagent_aged_creditorsARead-only
Aged creditors — unpaid supplier bills bucketed by how overdue they are. Shows what the company owes and for how long.
Inputs: asAt.
freeagent_aged_debtorsARead-only
Aged debtors — unpaid customer invoices bucketed by how overdue they are (not yet due, 1-30, 31-60, 61-90, 90+ days). Shows who owes what and for how long.
Inputs: asAt.
freeagent_company_summaryARead-only
FreeAgent company details — name, type, company registration number, VAT registration status, accounting year end and currency.
Inputs: no named parameters.
freeagent_create_billA
Record a supplier bill (an invoice the company has received and owes). Each line needs a spending category and a value including tax.
RECEIPTS: before asking the user for the PDF, search connected email tools (Gmail, Outlook/M365) for the supplier invoice and pass it as fileBase64 + fileName.
Inputs: dueOn (required), items (required), contact (required), datedOn (required), +8 more.
freeagent_create_contactA
Create a contact in FreeAgent — a client to invoice or a supplier to record bills against. Supply either an organisation name or a first/last name (or both).
Inputs: town, email, region, country, +9 more.
freeagent_create_expenseA
Create an expense in FreeAgent — for purchases on a personal card or cash that need claiming back. Provide vendor, date, amount, description and category. If categoryUrl is omitted, auto-selects from vendor mapping. Optionally pass bankAccountId to auto-match and explain a corresponding bank transaction (e.g. if the same purchase also appears on a company card).
RECEIPTS: Before asking the user for a file, search connected email tools (Gmail, Outlook/M365) for a matching invoice. Use vendor name, amount and date as search terms. Download the PDF and pass it as fileBase64 + fileName. Also check local sources (Downloads folder, etc.) if the user has mentioned them.
Inputs: vendor (required), datedOn (required), description (required), grossAmount (required), +8 more.
freeagent_create_invoiceA
Raise an invoice in FreeAgent. Created as a DRAFT — it is not sent to the client. Use freeagent_update_invoice_status with 'mark_as_sent' once you have issued it.
Find the contact with freeagent_list_contacts and the income category with freeagent_list_categories (income categories, e.g. 001 Sales).
Inputs: items (required), contact (required), datedOn (required), project, +6 more.
freeagent_create_mileage_expenseA
Create a mileage expense in FreeAgent. Provide either origin + destination (requires ORS_API_KEY or GOOGLE_MAPS_API_KEY for distance lookup) or manualMiles for the journey distance. Set roundTrip=true to double the distance.
The claim value is calculated by FreeAgent from the mileage rate configured on the account (this is what HMRC reporting in FreeAgent uses). ratePence / cumulativeMilesYTD only produce an advisory estimate in the response for cross-checking — they do not change what is filed.
Inputs: datedOn (required), description (required), origin, project, +7 more.
freeagent_create_taskA
Create a task on a FreeAgent project. Tasks carry the billing rate that logged time is charged at.
Inputs: name (required), project (required), status, currency, +3 more.
freeagent_create_timeslipA
Log time against a FreeAgent project task. Defaults to the authenticated user as the person who did the work. Find the task with freeagent_list_tasks.
Inputs: task (required), hours (required), datedOn (required), project (required), +2 more.
freeagent_delete_billADestructiveIdempotent
Permanently delete a FreeAgent bill.
Inputs: billId (required).
freeagent_delete_invoiceADestructiveIdempotent
Permanently delete a FreeAgent invoice. Only draft invoices can normally be deleted — cancel an issued invoice instead with freeagent_update_invoice_status.
Inputs: invoiceId (required).
freeagent_delete_timeslipBDestructiveIdempotent
Delete a logged timeslip from FreeAgent.
Inputs: timeslipId (required).
freeagent_explain_transactionAIdempotent
Approve or update a FreeAgent bank transaction explanation. Use this to:
Approve a 'marked for review' transaction (set markExplained=true)
Change the category or description of an explanation
Attach a receipt/invoice — PREFER filePath (a local file) or fileUrl (a download link); the server reads/encodes it. Re-attaching replaces any existing attachment. Get the explanationId from freeagent_list_transactions (explanation_id field).
RECEIPTS: Before asking the user for a file, search connected email tools (Gmail, Outlook/M365) for a matching invoice using vendor name, amount and date. Pass a download link as fileUrl, or save the PDF locally and pass filePath. Avoid fileBase64 for anything but tiny files — large inline base64 is unreliable. Also check local file sources (Downloads folder, etc.) if the user has mentioned them.
SAFETY: Only set markExplained=true when you have a confirmed receipt attached or the user has explicitly approved it.
Inputs: explanationId (required), fileUrl, category, fileName, +5 more.
freeagent_get_invoiceARead-only
Fetch a single FreeAgent invoice in full, including its line items.
Inputs: invoiceId (required).
freeagent_list_bank_accountsARead-only
List all bank accounts on the FreeAgent account. Returns account name, currency, current balance and status. Use this to find the bank account ID before listing transactions.
Inputs: no named parameters.
freeagent_list_billsARead-only
List FreeAgent bills — money the company owes to suppliers (accounts payable). Use view='open_or_overdue' to see what is still to pay.
Inputs: view, limit, toDate, contact, +2 more.
freeagent_list_categoriesARead-only
List FreeAgent expense categories (chart of accounts). Returns category URL, description, nominal code and group. Use the category URL when creating expenses or explaining transactions. Cached after first call.
Inputs: no named parameters.
freeagent_list_contactsARead-only
List FreeAgent contacts (clients and suppliers). Returns contact URL, name, email, status and outstanding account balance. Use the contact URL when raising an invoice or entering a supplier bill.
Inputs: view, limit, search.
freeagent_list_invoicesARead-only
List FreeAgent invoices with their status and outstanding balance. Use view='overdue' to chase late payers, 'open_or_overdue' for everything unpaid, or 'draft' for invoices not yet issued.
Inputs: view, limit, toDate, contact, +2 more.
freeagent_list_projectsARead-only
List FreeAgent projects. Returns project URL, name, status and contact. Use the project URL to tag an expense to a client engagement via freeagent_create_expense.
Inputs: view.
freeagent_list_tasksARead-only
List project tasks in FreeAgent. Time is always logged against a task, so use this to find the task URL before creating a timeslip.
Inputs: view, limit, project.
freeagent_list_timeslipsARead-only
List logged time in FreeAgent for a date range. Use view='unbilled' to find time that has not yet been invoiced. Returns per-project totals alongside the individual entries.
Inputs: toDate (required), fromDate (required), task, user, +3 more.
freeagent_list_transactionsARead-only
List bank account transactions from FreeAgent. By default returns unexplained (unreconciled) transactions. Use bankAccountId from freeagent_list_bank_accounts. Returns id, date, description, amount, and explanation details (category, marked_for_review) for each entry. After listing, if the task involves reconciliation, search available email or file sources for matching receipts — do not ask the user to provide files before checking email (Gmail, Outlook, etc.) and local sources first.
Inputs: bankAccountId (required), page, view, limit, +2 more.
freeagent_profit_and_lossARead-only
FreeAgent profit and loss summary — income, expenses, operating profit, corporation tax estimate, dividends and retained profit. Defaults to the current accounting year.
Inputs: toDate, fromDate.
freeagent_tax_timelineARead-only
Upcoming tax and filing deadlines from FreeAgent — VAT returns, corporation tax, Companies House filings, self assessment — with amounts due and dates.
Inputs: includePersonal.
freeagent_trial_balanceARead-only
FreeAgent trial balance — the balance on every nominal account. Credits are negative, debits positive. Useful for a full financial position.
Inputs: asAt, nonZeroOnly.
freeagent_update_invoice_statusADestructiveIdempotent
Change an invoice's status in FreeAgent: mark_as_sent (issue it), mark_as_draft (pull it back), mark_as_scheduled, or mark_as_cancelled. These change status only — no email is sent to the client.
Inputs: invoiceId (required), transition (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools map cleanly to a specific resource and action, such as invoices, contacts, bills, timeslips, or reports. Minor overlap exists between `freeagent_create_expense` and `freeagent_explain_transaction` because both can attach receipts and match bank transactions, but the descriptions make the primary intent reasonably clear.
The server uses a consistent `freeagent_` prefix and mostly follows a verb_resource naming pattern like `list_invoices`, `create_bill`, and `delete_timeslip`. The report tools break the pattern with noun-style names such as `freeagent_profit_and_loss`, `freeagent_trial_balance`, and `freeagent_tax_timeline`, but the deviation is minor and readable.
28 tools is above the comfortable management range, though the FreeAgent domain is broad: invoicing, banking, contacts, expenses, bills, timeslips, tasks, and reporting are all represented. The tools are not redundant or padded, but the overall number is heavy for an agent to scan and select from.
The server covers many core workflows, especially invoicing, bank reconciliation, expenses, and financial reporting. However, several resources have incomplete lifecycle coverage: contacts can be created and listed but not updated/deleted, expenses cannot be listed or updated, and invoices can only have their status changed, not their line items or amounts corrected.
Maintenance
Related MCP Connectors
Connect Claude to Dutch accounting software: e-Boekhouden invoices, contacts and ledgers.
IQ Books is an AI-native UK ledger that does the bookkeeping for you. Bank transactions arrive already coded, receipts and bills file themselves, invoices are allocated, the bank is reconciled, and VAT and MTD for Income Tax updates go to HMRC from it. Through this connector Claude can read the reports, raise invoices, record payments and code bank statements, with every change shown as a plan you approve first. UK businesses; the ledger is free for one business, and there is a free demo company to try.
Read FreeAgent contacts, invoices, bills, banking and reports; add contacts, draft invoices, time.
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAutomates FreshBooks invoicing and time tracking through Claude, allowing users to send invoices, list invoices, log billable hours, and get financial insights via natural language commands.2-
- AlicenseNot gradedqualityDmaintenanceEnables Claude to interact with freee accounting software through OAuth 2.0 authentication, supporting operations like transaction creation, account management, receipt uploads, and financial statement retrieval.MIT
- AlicenseAqualityCmaintenanceEnables Claude to interact with a Folio business bank account for managing accounts, transactions, receipts, bookkeeping, and payments as drafts.1414 npm6MIT
- AlicenseBqualityDmaintenanceEnables Claude Desktop to interact with freee accounting API for expense registration, transaction management, and receipt image processing.151MIT