FreeAgent MCP Server

A Model Context Protocol (MCP) server for the FreeAgent accounting API. Enables LLMs to manage contacts, invoices, estimates, bills, expenses, timeslips, projects, tasks, bank accounts, and more.

By my own admission, most of this project is vibe coded.

Features

• Broad FreeAgent coverage: contacts, invoices (incl. transitions and discounts), estimates (incl. transitions), bills, recurring invoices, price list items, expenses, timeslips, projects, tasks, bank accounts, bank transaction explanations, categories, company info, and users

• Intent-bundle tools: reconcile_bank_transaction, log_expense, and invoice_from_timeslips collapse multi-call sequences into single tool calls and resolve human-friendly hints (names, codes, references) to FreeAgent URLs server-side

• Optional tool-search mode (FREEAGENT_TOOL_SEARCH=true): collapses the tool catalog behind two meta-tools (freeagent_search_tools, freeagent_call_tool) so clients only pay the tool-definition token cost for tools they actually use

• MCP elicitation: create_invoice falls back to a form elicitation when contact is omitted (on clients that support it)

• Two deployment modes: local (stdio) or cloud (Vercel serverless via Streamable HTTP)

• OAuth 2.0: stateless JWT-based auth for serverless, or direct token for local use

• Tool annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint on every tool

• Zod validation: strict input schemas with .describe() on all fields

• Dual response formats: Markdown (human-readable) or JSON (structured)

• Pagination: proper header parsing with x-total-count and Link headers

• Rate limit handling: clear error messages with retry-after guidance

• Sandbox support: test safely against FreeAgent's sandbox environment

Related MCP server: FreeAgent MCP Server

Deployment Options

Local (stdio) - for Claude Desktop

1. Install and build:

   bun install
   bun run build

2. Set environment variables:

   export FREEAGENT_ACCESS_TOKEN="your_access_token"
   export FREEAGENT_USE_SANDBOX="true"  # optional

3. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "freeagent": {
         "command": "node",
         "args": ["/path/to/freeagent-mcp-server/dist/index.js"],
         "env": {
           "FREEAGENT_ACCESS_TOKEN": "your_token",
           "FREEAGENT_USE_SANDBOX": "true"
         }
       }
     }
   }

Vercel (Streamable HTTP) - for cloud access

See VERCEL_DEPLOYMENT.md for full instructions. Key points:

• Uses StreamableHTTPServerTransport in stateless mode (no sessions)

• OAuth 2.0 with PKCE via JWT-encoded tokens (no database needed)

• Handles POST (tool calls), GET (SSE streaming), and DELETE (returns 405 - stateless)

• Set PRODUCTION_URL (or rely on VERCEL_PROJECT_PRODUCTION_URL) for stable production OAuth callback URLs. Preview OAuth uses the request host (or VERCEL_URL) so short per-deploy hosts match FreeAgent * wildcards.

Required env vars: FREEAGENT_CLIENT_ID, FREEAGENT_CLIENT_SECRET, JWT_SECRET (stable secret required on Vercel so OAuth JWTs verify across serverless instances)

Tool-Search Mode (optional)

By default the server registers every catalog tool directly, which makes all ~50 tool definitions part of the MCP client's tools/list response. For clients with many connected MCP servers — where tool-definition tokens add up quickly — set:

export FREEAGENT_TOOL_SEARCH=true

In this mode the server exposes only two meta-tools:

The full catalog is still reachable — it's just loaded on demand. This mirrors the deferred-loading pattern used by Claude Code's internal ToolSearch.

Available Tools

See TOOLS.md for per-tool parameters and examples. Summary:

Contacts

Invoices

Estimates

Bills

Recurring Invoices

Price List Items

Expenses

Timeslips

Bank Accounts & Transactions

Projects & Tasks

Categories, Company & Users

Development

Prerequisites

• Bun (used for package management and running scripts)

• Node.js 22.x

Setup

bun install

Scripts

Project Structure

freeagent-mcp-server/
├── src/
│   ├── index.ts                       # Stdio server entry point
│   ├── constants.ts                   # Configuration constants & shared utilities
│   ├── types.ts                       # TypeScript type definitions
│   ├── schemas/
│   │   ├── index.ts                   # Zod validation schemas for all tools
│   │   ├── projects.ts                # Project-specific schemas
│   │   └── schemas.test.ts            # Schema validation tests
│   ├── services/
│   │   ├── api-client.ts              # FreeAgent API client (Axios)
│   │   ├── api-client.test.ts         # API client tests
│   │   ├── formatter.ts               # Response formatting utilities (incl. discount amount helper)
│   │   ├── formatter.test.ts          # Formatter tests
│   │   ├── resolvers.ts               # Shared resolvers (category / user / contact / bill hints → URLs)
│   │   ├── oauth-jwt.ts               # JWT-based OAuth provider (Vercel)
│   │   └── freeagent-auth.ts          # Token validation
│   └── tools/
│       ├── register.ts                # Shared tool definitions, registration, ToolContext (elicitation)
│       ├── contacts.ts                # Contact CRUD
│       ├── invoices.ts                # Invoice management (incl. elicitation fallback)
│       ├── transition-invoice.ts      # Invoice lifecycle transitions
│       ├── invoice-from-timeslips.ts  # Intent bundle: draft an invoice from unbilled time
│       ├── estimates.ts               # Estimates + transition_estimate
│       ├── bills.ts                   # Supplier bills
│       ├── recurring-invoices.ts      # Recurring invoice templates (read-only)
│       ├── price-list-items.ts        # Catalog items
│       ├── expenses.ts                # Expense & mileage tracking
│       ├── log-expense.ts             # Intent bundle: positive-amount expense logging
│       ├── timeslips.ts               # Time tracking (incl. update_timeslip)
│       ├── bank-accounts.ts           # Bank accounts & transactions
│       ├── bank-transactions.ts       # Transaction explanations
│       ├── reconcile.ts               # Intent bundle: reconcile a transaction in one call
│       ├── projects.ts                # Project management
│       ├── tasks.ts                   # Task management
│       ├── categories.ts              # Accounting categories
│       └── company.ts                 # Company info & users
├── api/
│   └── index.ts              # Vercel serverless entry point
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions CI (lint, test, build)
├── eslint.config.js          # ESLint flat config
├── vitest.config.ts          # Vitest configuration
├── vercel.json               # Vercel deployment config
├── package.json
└── tsconfig.json

CI

GitHub Actions runs on every push to main and on pull requests:

• Lint: ESLint with TypeScript rules

• Test: Vitest unit tests (no external API calls)

• Build: TypeScript compilation check

Rate Limiting

The server returns clear error messages with retry-after timing when rate limited.

Error Handling

All tool handlers return structured errors via { isError: true, content: [...] } (never thrown exceptions). Error messages are designed for LLM consumption with actionable guidance:

Security

• Access tokens are never logged or committed

• JWT tokens use HS256 signing with configurable secret

• PKCE is used for the OAuth authorization flow

• Strict Zod schemas reject unexpected input fields

• Bearer auth middleware protects all MCP endpoints

License

MIT

Links

• FreeAgent API Docs

• MCP Specification

• FreeAgent Developer Dashboard