freeagent-mcp-server
An MCP server that connects an AI client to the FreeAgent accounting API, exposing read and (optionally) write tools across the business's finances.
Company & tax: read company details, business categories, and the tax timeline.
Users: list/look up users and current user; create, update, and delete users (sensitive, off by default).
Contacts: list/get/create/update/delete clients and suppliers, with filtering and sorting (changing an email is sensitive).
Projects & tasks: full CRUD for projects and their billable tasks, with filters by view, contact, and project.
Timeslips: list/get/create/update/delete time entries, plus start and stop a running timer.
Invoices: list/get/create/update/delete, mark as sent/draft/cancelled, and email them (sensitive).
Estimates: list/get/create/update/delete, mark sent or approved.
Bills: list/get/create/update/delete supplier bills, attaching a local receipt file (PDF/PNG/JPEG/GIF, max 5MB).
Credit notes: list/get/create/update/delete.
Expenses: list/get/create/update/delete, with an attached receipt.
Banking: list/get bank accounts, update/delete them, and list/get bank transactions (creating accounts is sensitive).
Categories: list the chart of accounts and get a category by nominal code.
Accounting reports: profit and loss, balance sheet, opening balances, trial balance, and trial balance opening balances.
Attachments: download an attachment into the configured
FREEAGENT_ATTACHMENTS_DIRonly.Safety controls: every tool is annotated read/write/destructive, list tools paginate (up to 100 per page), sensitive tools are off unless enabled, and a read-only mode registers only reading tools.
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 List my unpaid invoices"
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
An MCP server that gives Claude, Codex, Cursor, VS Code, Gemini CLI or any other MCP client the FreeAgent accounting API: 85 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, and saved to, one folder you choose.
Contents
Related MCP server: Cuéntica MCP
How it fits together
Claude, Codex, Cursor, VS Code, … ──stdio──▶ freeagent-mcp-server (Node.js, on your machine)
├─ 85 tools; sensitive ones only with FREEAGENT_ENABLE_SENSITIVE_TOOLS
├─ OAuth2 tokens in ~/.freeagent-mcp/tokens.json, refreshed automatically
├─ receipts read from / saved to 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.
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.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 authAdd it to Claude:
claude_desktop_config.jsonfor Claude Desktop and Cowork (on macOS in~/Library/Application Support/Claude/),.mcp.jsonfor 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
Area | Tools | |
Company | 3 | Company details, business categories, tax timeline |
Users | 6 | List and look up users; create, update, delete (sensitive) |
Contacts | 5 | Clients and suppliers (changing an email is sensitive) |
Projects, Tasks | 5, 5 | Projects and their billable tasks |
Timeslips | 7 | Time tracking, with a start/stop timer |
Invoices | 9 | Create, update, mark sent, draft or cancelled; email (sensitive) |
Estimates | 7 | Quotes, estimates and proposals, sent and approved |
Bills | 5 | Supplier bills, with a receipt attached |
Credit notes | 5 | Credit notes |
Expenses | 5 | Expenses, with a receipt attached |
Banking | 7 | Bank accounts and their transactions; create (sensitive) |
Categories | 2 | The chart of accounts |
Accounting | 5 | Profit and loss, balance sheet, trial balance |
List tools page through results (page, per_page up to 100). Every tool, its
endpoint and example prompts: docs/tools.md.
Settings
Variable | Required | What |
| Yes | Your app's OAuth2 credentials |
| No |
|
| No |
|
| No |
|
| To attach receipts | The one folder |
| No | Legacy direct token; API base override |
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 buildCI 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.
Doc | What |
Step by step: client ID and secret, connecting your account, adding it to your AI app | |
Every setting, signing in, the sandbox, config for each MCP client | |
All 85 tools, pagination, annotations, example prompts | |
The threat model, sensitive tools, attachments, tokens | |
Common errors and fixes | |
Building, testing, what's where, adding a tool | |
How to work here, and the rules that don't bend | |
The release procedure | |
What changed in each version |
Links
License
MIT
Available Tools
72 toolsfreeagent_create_billB
Create a new bill in FreeAgent. bill_items should be a JSON string array of objects with category (URL), description, total_value, and sales_tax_rate.
Inputs: due_on (required), contact (required), dated_on (required), reference (required), +4 more.
freeagent_create_contactA
Create a new contact in FreeAgent. Must provide either first_name and last_name, or organisation_name.
Inputs: town, email, country, address1, +8 more.
freeagent_create_credit_noteC
Create a new credit note in FreeAgent
Inputs: contact (required), dated_on (required), comments, currency, +2 more.
freeagent_create_estimateC
Create a new estimate in FreeAgent
Inputs: contact (required), currency (required), dated_on (required), estimate_type (required), +4 more.
freeagent_create_expenseC
Create a new expense in FreeAgent
Inputs: user (required), category (required), dated_on (required), gross_value (required), +7 more.
freeagent_create_invoiceC
Create a new invoice in FreeAgent
Inputs: contact (required), dated_on (required), payment_terms_in_days (required), comments, +6 more.
freeagent_create_projectC
Create a new project in FreeAgent
Inputs: name (required), budget (required), status (required), contact (required), +9 more.
freeagent_create_taskCreate TaskB
Create a new task in FreeAgent. The project URL is required and passed as a query parameter.
Inputs: name (required), project (required), status, is_billable, +2 more.
freeagent_create_timeslipCreate TimeslipB
Create a new timeslip in FreeAgent for tracking time against a project task.
Inputs: task (required), user (required), hours (required), project (required), +2 more.
freeagent_delete_bank_accountCDestructive
Delete a bank account from FreeAgent
Inputs: bank_account_id (required).
freeagent_delete_billBDestructive
Delete a bill from FreeAgent
Inputs: bill_id (required).
freeagent_delete_contactCDestructive
Delete a contact from FreeAgent
Inputs: contact_id (required).
freeagent_delete_credit_noteBDestructive
Delete a credit note from FreeAgent
Inputs: credit_note_id (required).
freeagent_delete_estimateCDestructive
Delete an estimate from FreeAgent
Inputs: estimate_id (required).
freeagent_delete_expenseBDestructive
Delete an expense from FreeAgent
Inputs: expense_id (required).
freeagent_delete_invoiceCDestructive
Delete an invoice from FreeAgent
Inputs: invoice_id (required).
freeagent_delete_projectCDestructive
Delete a project from FreeAgent
Inputs: project_id (required).
freeagent_delete_taskDelete TaskCDestructive
Delete a task from FreeAgent.
Inputs: task_id (required).
freeagent_delete_timeslipDelete TimeslipCDestructive
Delete a timeslip from FreeAgent.
Inputs: timeslip_id (required).
freeagent_download_attachmentA
Download a FreeAgent attachment (e.g. an expense or bill receipt) into FREEAGENT_ATTACHMENTS_DIR. Takes the attachment ID from an attachment URL such as https://api.freeagent.com/v2/attachments/123. Never overwrites: a clashing name gets a ' (n)' suffix. Returns the saved path, not the download link.
Inputs: attachment_id (required).
freeagent_get_balance_sheetBRead-only
Get the balance sheet from FreeAgent, optionally as at a specific date
Inputs: as_at_date.
freeagent_get_bank_accountBRead-only
Get a single bank account from FreeAgent by ID
Inputs: bank_account_id (required).
freeagent_get_bank_transactionARead-only
Get a single bank transaction from FreeAgent by ID
Inputs: bank_transaction_id (required).
freeagent_get_billCRead-only
Get a single bill from FreeAgent by ID
Inputs: bill_id (required).
freeagent_get_categoryBRead-only
Get a single category from FreeAgent by nominal code
Inputs: nominal_code (required).
freeagent_get_companyGet CompanyARead-only
Get information about the authenticated FreeAgent company, including name, type, currency, and other settings.
Inputs: no named parameters.
freeagent_get_contactBRead-only
Get a single contact from FreeAgent by ID
Inputs: contact_id (required).
freeagent_get_credit_noteARead-only
Get a single credit note from FreeAgent by ID
Inputs: credit_note_id (required).
freeagent_get_current_userARead-only
Get the currently authenticated user
Inputs: no named parameters.
freeagent_get_estimateBRead-only
Get a single estimate from FreeAgent by ID
Inputs: estimate_id (required).
freeagent_get_expenseBRead-only
Get a single expense from FreeAgent by ID
Inputs: expense_id (required).
freeagent_get_invoiceARead-only
Get a single invoice from FreeAgent by ID
Inputs: invoice_id (required).
freeagent_get_opening_balancesBRead-only
Get the opening balances from the FreeAgent balance sheet
Inputs: no named parameters.
freeagent_get_profit_and_lossBRead-only
Get the profit and loss summary from FreeAgent with optional date range filtering
Inputs: to_date, from_date.
freeagent_get_projectBRead-only
Get a single project from FreeAgent by ID
Inputs: project_id (required).
freeagent_get_taskGet TaskCRead-only
Get a specific task by ID from FreeAgent.
Inputs: task_id (required).
freeagent_get_tax_timelineGet Tax TimelineARead-only
Get the tax timeline for the company, showing upcoming tax deadlines and obligations.
Inputs: no named parameters.
freeagent_get_timeslipGet TimeslipBRead-only
Get a single timeslip by its ID.
Inputs: timeslip_id (required).
freeagent_get_trial_balanceBRead-only
Get the trial balance summary from FreeAgent with optional date range filtering
Inputs: to_date, from_date.
freeagent_get_trial_balance_openingCRead-only
Get the trial balance opening balances from FreeAgent
Inputs: no named parameters.
freeagent_get_userCRead-only
Get a specific user by ID
Inputs: user_id (required).
freeagent_list_bank_accountsBRead-only
List bank accounts from FreeAgent with optional view filter
Inputs: page, view, per_page.
freeagent_list_bank_transactionsCRead-only
List bank transactions from FreeAgent for a specific bank account
Inputs: bank_account (required), page, view, to_date, +3 more.
freeagent_list_billsBRead-only
List bills from FreeAgent with optional filtering by view, date range, contact, or project
Inputs: page, view, contact, project, +5 more.
freeagent_list_business_categoriesList Business CategoriesARead-only
List the available business categories for the company. These are used to classify the type of business.
Inputs: no named parameters.
freeagent_list_categoriesBRead-only
List all categories from FreeAgent, optionally including sub-accounts
Inputs: sub_accounts.
freeagent_list_contactsCRead-only
List contacts from FreeAgent with optional filtering and sorting
Inputs: page, sort, view, per_page, +1 more.
freeagent_list_credit_notesBRead-only
List credit notes from FreeAgent with optional filtering and sorting
Inputs: page, sort, view, contact, +4 more.
freeagent_list_estimatesCRead-only
List estimates from FreeAgent with optional filtering
Inputs: page, view, contact, project, +5 more.
freeagent_list_expensesARead-only
List expenses from FreeAgent with optional filtering by view, date range, and project
Inputs: page, view, project, to_date, +3 more.
freeagent_list_invoicesBRead-only
List invoices from FreeAgent, optionally filtered by view, sort order, contact, project, or updated date
Inputs: page, sort, view, contact, +4 more.
freeagent_list_projectsBRead-only
List projects from FreeAgent, optionally filtered by view, sort order, or contact
Inputs: page, sort, view, contact, +1 more.
freeagent_list_tasksList TasksARead-only
List tasks from FreeAgent. Optionally filter by view, project, or updated_since.
Inputs: page, sort, view, project, +2 more.
freeagent_list_timeslipsList TimeslipsBRead-only
List timeslips from FreeAgent. Can be filtered by date range, user, task, project, and billing status.
Inputs: page, task, user, view, +5 more.
freeagent_list_usersCRead-only
List all users in the FreeAgent account
Inputs: page, view, per_page.
freeagent_mark_estimate_as_approvedC
Mark an estimate as approved in FreeAgent
Inputs: estimate_id (required).
freeagent_mark_estimate_as_sentC
Mark an estimate as sent in FreeAgent
Inputs: estimate_id (required).
freeagent_mark_invoice_as_cancelledCDestructive
Cancel an invoice in FreeAgent
Inputs: invoice_id (required).
freeagent_mark_invoice_as_draftC
Mark an invoice as draft in FreeAgent
Inputs: invoice_id (required).
freeagent_mark_invoice_as_sentC
Mark an invoice as sent in FreeAgent
Inputs: invoice_id (required).
freeagent_start_timerStart TimerA
Start a running timer on a timeslip. The timeslip will accumulate time until the timer is stopped.
Inputs: timeslip_id (required).
freeagent_stop_timerStop TimerB
Stop a running timer on a timeslip.
Inputs: timeslip_id (required).
freeagent_update_bank_accountCDestructive
Update an existing bank account in FreeAgent
Inputs: bank_account_id (required), name, bank_name, is_primary.
freeagent_update_billCDestructive
Update an existing bill in FreeAgent
Inputs: bill_id (required), due_on, comments, dated_on, +2 more.
freeagent_update_contactCDestructive
Update an existing contact in FreeAgent
Inputs: contact_id (required), town, country, address1, +8 more.
freeagent_update_credit_noteCDestructive
Update an existing credit note in FreeAgent
Inputs: credit_note_id (required), comments, dated_on, payment_terms_in_days.
freeagent_update_estimateCDestructive
Update an existing estimate in FreeAgent
Inputs: estimate_id (required), comments, dated_on, reference, +1 more.
freeagent_update_expenseCDestructive
Update an existing expense in FreeAgent
Inputs: expense_id (required), project, category, dated_on, +5 more.
freeagent_update_invoiceCDestructive
Update an existing invoice in FreeAgent
Inputs: invoice_id (required), comments, currency, dated_on, +2 more.
freeagent_update_projectCDestructive
Update an existing project in FreeAgent
Inputs: project_id (required), name, budget, status, +9 more.
freeagent_update_taskUpdate TaskCDestructive
Update an existing task in FreeAgent.
Inputs: task_id (required), name, status, is_billable, +2 more.
freeagent_update_timeslipUpdate TimeslipCDestructive
Update an existing timeslip in FreeAgent.
Inputs: timeslip_id (required), task, hours, comment, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 72 tools
Each tool maps to a distinct FreeAgent resource and action, with clear separation between invoices, estimates, expenses, bills, credit notes, contacts, projects, tasks, timeslips, bank accounts, transactions, and reports. Minor look-alikes such as list_categories vs list_business_categories are clarified by their descriptions.
All tools use a consistent freeagent_ prefix followed by snake_case verb_noun naming such as get_invoice, create_task, update_project, and delete_bill. The few state-transition names like mark_invoice_as_sent also follow the same predictable pattern.
With 72 tools, the server is far beyond a practical agent-sized surface and creates a heavy selection burden. Although the tools map to a broad accounting domain, the count is extreme enough to undermine coherence as a single MCP toolset.
Core accounting entities such as invoices, estimates, expenses, bills, contacts, projects, tasks, and timeslips have solid CRUD coverage, and reports are included. However, notable lifecycle gaps remain, especially around bank transactions, payments/reconciliation, user management, and attachment handling beyond download.
Maintenance
Related MCP Connectors
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
Headless API-first double-entry accounting & bookkeeping engine. 84 MCP tools over HTTP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that enables AI agents to interact with QuickBooks Online accounts to manage invoices, customers, payments, and financial reports. It provides 20 tools to automate accounting workflows and retrieve financial data through natural language interfaces.-
- AlicenseBqualityDmaintenanceMCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.5931 PyPI2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for the FreeAgent accounting API, enabling LLMs to securely access and manage accounting data including contacts, invoices, bills, bank transactions, and more.5 npm1MIT
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server for the FreeAgent accounting API, enabling LLMs to manage contacts, invoices, estimates, bills, expenses, timeslips, projects, tasks, bank accounts, and more.462 npm10MIT