Skip to main content
Glama
freeagent-mcp-server

freeagent-mcp-server

by samaxbytez

freeagent-mcp-server

CI npm version Node.js 24+ MCP SDK 1.32 License: MIT

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.

  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

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

FREEAGENT_CLIENT_ID, FREEAGENT_CLIENT_SECRET

Yes

Your app's OAuth2 credentials

FREEAGENT_SANDBOX

No

true to use the FreeAgent sandbox

FREEAGENT_ENABLE_SENSITIVE_TOOLS

No

true to turn on user management, invoice emailing, adding bank accounts and changing a contact's email

FREEAGENT_READ_ONLY

No

true to register only tools that read: no creates, updates, deletes, emails or downloads

FREEAGENT_ATTACHMENTS_DIR

To attach receipts

The one folder attachment_path reads from and freeagent_download_attachment saves to

FREEAGENT_ACCESS_TOKEN, FREEAGENT_BASE_URL

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 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.

Doc

What

docs/setup.md

Step by step: client ID and secret, connecting your account, adding it to your AI app

docs/configuration.md

Every setting, signing in, the sandbox, config for each MCP client

docs/tools.md

All 85 tools, pagination, annotations, example prompts

docs/security.md

The threat model, sensitive tools, attachments, tokens

docs/troubleshooting.md

Common errors and fixes

docs/development.md

Building, testing, what's where, adding a tool

AGENTS.md

How to work here, and the rules that don't bend

RELEASING.md

The release procedure

CHANGELOG.md

What changed in each version

License

MIT

Available Tools

72 tools
freeagent_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_accountC
Destructive

Delete a bank account from FreeAgent

Inputs: bank_account_id (required).

freeagent_delete_billB
Destructive

Delete a bill from FreeAgent

Inputs: bill_id (required).

freeagent_delete_contactC
Destructive

Delete a contact from FreeAgent

Inputs: contact_id (required).

freeagent_delete_credit_noteB
Destructive

Delete a credit note from FreeAgent

Inputs: credit_note_id (required).

freeagent_delete_estimateC
Destructive

Delete an estimate from FreeAgent

Inputs: estimate_id (required).

freeagent_delete_expenseB
Destructive

Delete an expense from FreeAgent

Inputs: expense_id (required).

freeagent_delete_invoiceC
Destructive

Delete an invoice from FreeAgent

Inputs: invoice_id (required).

freeagent_delete_projectC
Destructive

Delete a project from FreeAgent

Inputs: project_id (required).

freeagent_delete_taskDelete TaskC
Destructive

Delete a task from FreeAgent.

Inputs: task_id (required).

freeagent_delete_timeslipDelete TimeslipC
Destructive

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_sheetB
Read-only

Get the balance sheet from FreeAgent, optionally as at a specific date

Inputs: as_at_date.

freeagent_get_bank_accountB
Read-only

Get a single bank account from FreeAgent by ID

Inputs: bank_account_id (required).

freeagent_get_bank_transactionA
Read-only

Get a single bank transaction from FreeAgent by ID

Inputs: bank_transaction_id (required).

freeagent_get_billC
Read-only

Get a single bill from FreeAgent by ID

Inputs: bill_id (required).

freeagent_get_categoryB
Read-only

Get a single category from FreeAgent by nominal code

Inputs: nominal_code (required).

freeagent_get_companyGet CompanyA
Read-only

Get information about the authenticated FreeAgent company, including name, type, currency, and other settings.

Inputs: no named parameters.

freeagent_get_contactB
Read-only

Get a single contact from FreeAgent by ID

Inputs: contact_id (required).

freeagent_get_credit_noteA
Read-only

Get a single credit note from FreeAgent by ID

Inputs: credit_note_id (required).

freeagent_get_current_userA
Read-only

Get the currently authenticated user

Inputs: no named parameters.

freeagent_get_estimateB
Read-only

Get a single estimate from FreeAgent by ID

Inputs: estimate_id (required).

freeagent_get_expenseB
Read-only

Get a single expense from FreeAgent by ID

Inputs: expense_id (required).

freeagent_get_invoiceA
Read-only

Get a single invoice from FreeAgent by ID

Inputs: invoice_id (required).

freeagent_get_opening_balancesB
Read-only

Get the opening balances from the FreeAgent balance sheet

Inputs: no named parameters.

freeagent_get_profit_and_lossB
Read-only

Get the profit and loss summary from FreeAgent with optional date range filtering

Inputs: to_date, from_date.

freeagent_get_projectB
Read-only

Get a single project from FreeAgent by ID

Inputs: project_id (required).

freeagent_get_taskGet TaskC
Read-only

Get a specific task by ID from FreeAgent.

Inputs: task_id (required).

freeagent_get_tax_timelineGet Tax TimelineA
Read-only

Get the tax timeline for the company, showing upcoming tax deadlines and obligations.

Inputs: no named parameters.

freeagent_get_timeslipGet TimeslipB
Read-only

Get a single timeslip by its ID.

Inputs: timeslip_id (required).

freeagent_get_trial_balanceB
Read-only

Get the trial balance summary from FreeAgent with optional date range filtering

Inputs: to_date, from_date.

freeagent_get_trial_balance_openingC
Read-only

Get the trial balance opening balances from FreeAgent

Inputs: no named parameters.

freeagent_get_userC
Read-only

Get a specific user by ID

Inputs: user_id (required).

freeagent_list_bank_accountsB
Read-only

List bank accounts from FreeAgent with optional view filter

Inputs: page, view, per_page.

freeagent_list_bank_transactionsC
Read-only

List bank transactions from FreeAgent for a specific bank account

Inputs: bank_account (required), page, view, to_date, +3 more.

freeagent_list_billsB
Read-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 CategoriesA
Read-only

List the available business categories for the company. These are used to classify the type of business.

Inputs: no named parameters.

freeagent_list_categoriesB
Read-only

List all categories from FreeAgent, optionally including sub-accounts

Inputs: sub_accounts.

freeagent_list_contactsC
Read-only

List contacts from FreeAgent with optional filtering and sorting

Inputs: page, sort, view, per_page, +1 more.

freeagent_list_credit_notesB
Read-only

List credit notes from FreeAgent with optional filtering and sorting

Inputs: page, sort, view, contact, +4 more.

freeagent_list_estimatesC
Read-only

List estimates from FreeAgent with optional filtering

Inputs: page, view, contact, project, +5 more.

freeagent_list_expensesA
Read-only

List expenses from FreeAgent with optional filtering by view, date range, and project

Inputs: page, view, project, to_date, +3 more.

freeagent_list_invoicesB
Read-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_projectsB
Read-only

List projects from FreeAgent, optionally filtered by view, sort order, or contact

Inputs: page, sort, view, contact, +1 more.

freeagent_list_tasksList TasksA
Read-only

List tasks from FreeAgent. Optionally filter by view, project, or updated_since.

Inputs: page, sort, view, project, +2 more.

freeagent_list_timeslipsList TimeslipsB
Read-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_usersC
Read-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_cancelledC
Destructive

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_accountC
Destructive

Update an existing bank account in FreeAgent

Inputs: bank_account_id (required), name, bank_name, is_primary.

freeagent_update_billC
Destructive

Update an existing bill in FreeAgent

Inputs: bill_id (required), due_on, comments, dated_on, +2 more.

freeagent_update_contactC
Destructive

Update an existing contact in FreeAgent

Inputs: contact_id (required), town, country, address1, +8 more.

freeagent_update_credit_noteC
Destructive

Update an existing credit note in FreeAgent

Inputs: credit_note_id (required), comments, dated_on, payment_terms_in_days.

freeagent_update_estimateC
Destructive

Update an existing estimate in FreeAgent

Inputs: estimate_id (required), comments, dated_on, reference, +1 more.

freeagent_update_expenseC
Destructive

Update an existing expense in FreeAgent

Inputs: expense_id (required), project, category, dated_on, +5 more.

freeagent_update_invoiceC
Destructive

Update an existing invoice in FreeAgent

Inputs: invoice_id (required), comments, currency, dated_on, +2 more.

freeagent_update_projectC
Destructive

Update an existing project in FreeAgent

Inputs: project_id (required), name, budget, status, +9 more.

freeagent_update_taskUpdate TaskC
Destructive

Update an existing task in FreeAgent.

Inputs: task_id (required), name, status, is_billable, +2 more.

freeagent_update_timeslipUpdate TimeslipC
Destructive

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

    B3/5.0

    Scored across 72 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count1/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An 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.
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.
      59
      31 PyPI
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for the FreeAgent accounting API, enabling LLMs to securely access and manage accounting data including contacts, invoices, bills, bank transactions, and more.
      5 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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 npm
      10
      MIT