FreeAgent MCP Server

MCP (Model Context Protocol) server for the FreeAgent accounting API. Enables LLMs to securely access and manage accounting data including contacts, invoices, bills, bank transactions, and more.

Prerequisites

• Node.js 24 LTS or later
• A FreeAgent account with API access
• FreeAgent API credentials (Client ID and Secret)

Installation

From npm (recommended)

npm install -g @stupidcodefactory/freeagent-mcp-server

From source

git clone https://github.com/StupidCodeFactory/freeagent-mcp.git
cd freeagent-mcp
npm install
npm run build

Configuration

1. Get FreeAgent API Credentials

1. Log in to your FreeAgent account
2. Go to Settings → Integrations → Developer Dashboard
3. Create a new app to get your Client ID and Client Secret
4. Set the redirect URI to http://localhost:3000/callback

2. Set Environment Variables

Create a .env file or export the following environment variables:

export FREEAGENT_CLIENT_ID="your_client_id"
export FREEAGENT_CLIENT_SECRET="your_client_secret"
export FREEAGENT_REDIRECT_URI="http://localhost:3000/callback"
export FREEAGENT_ENVIRONMENT="sandbox"  # or "production"

Optional:

export TOKEN_ENCRYPTION_KEY="$(openssl rand -hex 32)"  # For persistent token storage
export LOG_LEVEL="info"

Usage with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "freeagent": {
      "command": "npx",
      "args": ["@stupidcodefactory/freeagent-mcp-server"],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_REDIRECT_URI": "http://localhost:3000/callback",
        "FREEAGENT_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["/path/to/freeagent-mcp/dist/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_REDIRECT_URI": "http://localhost:3000/callback",
        "FREEAGENT_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Authentication

On first use, the server will provide an authorization URL. Visit this URL to authorize the app with your FreeAgent account. After authorization, tokens are stored and refreshed automatically.

Available Resources

| Resource | URI | Description | |----------|-----|-------------| | Company | freeagent://company | Company profile and settings | | Contacts | freeagent://contacts | Clients and suppliers | | Invoices | freeagent://invoices | Sales invoices | | Bills | freeagent://bills | Supplier bills | | Bank Accounts | freeagent://bank_accounts | Bank account list | | Bank Transactions | freeagent://bank_transactions?bank_account={id} | Transaction feed | | Projects | freeagent://projects | Projects | | Timeslips | freeagent://timeslips | Time entries | | Expenses | freeagent://expenses | Expense claims | | Categories | freeagent://categories | Account categories | | Users | freeagent://users | Team members |

Available Tools

Invoices

• create_invoice - Create a new invoice
• update_invoice - Update a draft invoice
• send_invoice - Email invoice to contact
• mark_invoice_sent - Mark as sent without emailing
• mark_invoice_paid - Record payment
• delete_invoice - Delete draft invoice

Contacts

• create_contact - Add new client/supplier
• update_contact - Update contact details
• delete_contact - Remove contact

Bank Transactions

• explain_transaction - Categorize transaction
• match_transaction_to_invoice - Match to invoice payment
• match_transaction_to_bill - Match to bill payment
• split_transaction - Split across categories
• unexplain_transaction - Remove explanation

Bank Transaction Explanations

• list_bank_transaction_explanations - List all explanations for a bank account
• get_bank_transaction_explanation - Get explanation details including attachment info
• create_bank_transaction_explanation - Create explanation (payment, invoice receipt, bill payment, transfer, etc.)
• update_bank_transaction_explanation - Update existing explanation
• delete_bank_transaction_explanation - Delete explanation
• upload_receipt - Upload receipt/attachment (PNG, JPEG, GIF, PDF, max 5MB)

Bills

• create_bill - Record supplier bill
• update_bill - Modify bill
• delete_bill - Remove bill

Projects

• create_project - Create project
• update_project - Update project
• create_task - Add task to project
• create_timeslip - Log time entry

Queries

• list_unpaid_invoices - Get overdue/open invoices
• get_bank_summary - Aggregate balances
• search_transactions - Search by description
• get_unexplained_transactions - List unexplained transactions

Available Prompts

• monthly_expense_summary - Categorized expense report
• invoice_from_description - Create invoice from natural language
• cash_flow_forecast - Project cash position (30/60/90 days)
• overdue_invoice_followup - Draft reminder emails
• transaction_categorization - Suggest categories for unexplained transactions
• project_profitability - Analyze project margins
• quarterly_tax_estimate - Estimate tax liability

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

# Build
npm run build

License

MIT