Merge Unified's FreshBooks integration Merge Agent Handler's FreshBooks MCP server

Connect your AI Agents to FreshBooks in minutes

Merge lets you securely connect your agents to FreshBooks and thousands of tools instantly

Start building for free

Read docs

FreshBooks

Learn more about Merge Agent Handler

Available tools

validate_credentials

Validate the OAuth credentials and return information about the authenticated user.

list_clients

List all clients. Supports pagination and filtering by email or organization.

get_client

Get a specific client by ID with full details including contact info and outstanding balance.

create_client_tool

Create a new client. Provide at least an email or organization name.

update_client

Update a client's information. Only provided fields will be updated.

delete_client

Delete a client by setting their visibility state to deleted.

list_expenses

List all expenses. Supports pagination and filtering by category or client.

get_expense

Get a specific expense by ID with full details including category and tax info.

create_expense

Create a new expense. Requires categoryid, amount, date, and staffid.

update_expense

Update an expense. Only provided fields will be updated.

delete_expense

Delete an expense by setting its visibility state to deleted.

list_invoices

List all invoices. Supports pagination and filtering by status or client ID.

get_invoice

Get a specific invoice by ID with full details including line items and payment status.

create_invoice

Create a new invoice. Requires customerid, create_date, and at least one line item.

update_invoice

Update an invoice. Only provided fields will be updated.

delete_invoice

Delete an invoice by setting its visibility state to deleted.

send_invoice

Send an invoice by email to specified recipients.

mark_invoice_sent

Mark an invoice as sent without actually sending an email.

list_items

List all billable items/services. Supports pagination.

get_item

Get a specific billable item by ID with full details.

create_item

Create a new billable item/service. Requires name and unit_cost.

update_item

Update a billable item. Only provided fields will be updated.

delete_item

Delete a billable item by setting its visibility state to deleted.

list_payments

List all payments. Supports pagination and filtering by invoice or client.

get_payment

Get a specific payment by ID with full details.

create_payment

Create a new payment. Requires invoiceid, amount, and date.

update_payment

Update a payment. Only provided fields will be updated.

delete_payment

Delete a payment by setting its visibility state to deleted.

list_projects

List all projects. Requires business_id. Supports pagination and filtering by active status.

get_project

Get a specific project by ID with full details. Requires business_id.

create_project

Create a new project. Requires business_id and title.

update_project

Update a project. Requires business_id. Only provided fields will be updated.

delete_project

Delete a project. Requires business_id.

list_time_entries

List all time entries. Requires business_id. Supports pagination and filtering by project or date range.

get_time_entry

Get a specific time entry by ID with full details. Requires business_id.

create_time_entry

Create a new time entry. Requires businessid and startedat. Either duration or a running timer is required.

update_time_entry

Update a time entry. Requires business_id. Only provided fields will be updated.

delete_time_entry

Delete a time entry. Requires business_id.

validate_credential

Validate FreshBooks credentials. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's FreshBooks MCP server

What is a FreshBooks MCP?

It's an MCP server that gives your agents access to FreshBooks via tools. Your agents can invoke these tools to create and send invoices, track expenses, log time entries, manage client records, and more.

FreshBooks doesn't offer an official MCP server, but you can use one from a third-party platform, like Merge Agent Handler.

How can I use the FreshBooks MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Automated invoice generation on project completion: When a project milestone is marked complete in a tool like Asana, an agent calls <code class="blog_inline-code">create_invoice</code> to generate a FreshBooks invoice with the relevant line items and calls <code class="blog_inline-code">send_invoice</code> to deliver it to the client immediately, with no manual steps in between

Expense logging from receipt data: When a receipt is parsed from an email or uploaded to a document system, an agent calls <code class="blog_inline-code">create_expense</code> to log it in FreshBooks against the appropriate project and category, eliminating manual entry from the accounting workflow

Time entry sync from tracking tools: When a time log is submitted in an external tracker, an agent calls <code class="blog_inline-code">create_time_entry</code> to mirror the billable hours in FreshBooks against the correct project and client, keeping billing records consistent across tools without duplication

Overdue invoice follow-up digest: On a weekly schedule, an agent calls <code class="blog_inline-code">list_invoices</code> filtered by unpaid status and past due date, compiles a structured list of outstanding balances by client, and posts it to Slack so the team knows who needs a follow-up without logging into FreshBooks

What are popular tools for FreshBooks' MCP server?

Here are some of the most commonly used tools:

<code class="blog_inline-code">list_invoices</code> retrieves all invoices for an account, filterable by status, client, or date range. Good for agents that need to audit billing activity, identify overdue accounts, or pull invoice history before taking a downstream action

<code class="blog_inline-code">create_invoice</code> generates a new invoice in FreshBooks for a specified client with line items, due date, and tax details. Use this when an agent needs to automate invoice creation in response to a trigger in another system, like a completed project or a closed deal

<code class="blog_inline-code">send_invoice</code> delivers an existing invoice to the client via email directly from FreshBooks. Call this after creating an invoice when an agent needs to complete the full billing cycle without any manual steps

<code class="blog_inline-code">create_expense</code> logs a new expense against a project or expense category with the provided amount and description. Helpful when an agent is automating expense capture from a receipt parser, a card transaction feed, or an approval workflow

<code class="blog_inline-code">create_time_entry</code> records billable hours against a specified project and client. Use this when an agent needs to sync time logs from an external tracker into FreshBooks to keep billable hours accurate for invoicing

<code class="blog_inline-code">list_payments</code> retrieves payment records filterable by client or date range. Useful for agents that need to verify whether an invoice has been paid before taking an action, or generate a cash flow summary for a given period

What makes Merge Agent Handler's FreshBooks MCP server better than alternative FreshBooks MCP servers?

Here is what makes Merge Agent Handler's FreshBooks MCP server a stronger choice than building your own or using an alternative:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For FreshBooks, this means you can prevent invoice amounts, client financial details, and payment records from being exposed even when the agent has broad read access to your account

Managed authentication and credentials: Merge stores and refreshes FreshBooks credentials on your behalf. You never expose OAuth tokens to an agent directly or handle re-authentication when credentials expire

Real-time observability and audit trail: Every tool call made against FreshBooks is logged with timestamp, tool name, input parameters, and response metadata. You can see exactly what invoices an agent created, what expenses it logged, or what payment data it read without adding any custom logging

Tool Packs and controlled access: Tool Packs let you bundle specific FreshBooks tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's FreshBooks MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the FreshBooks connector. Choose which tools to include: enable read tools like <code class="blog_inline-code">list_invoices</code> and <code class="blog_inline-code">list_payments</code> for reporting use cases, or add write tools like <code class="blog_inline-code">create_invoice</code> and <code class="blog_inline-code">send_invoice</code> if your agent needs to generate and deliver invoices.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate FreshBooks by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your FreshBooks tools are now accessible through that endpoint.