How to Use the FreshBooks MCP in Windsurf

Q: How do I configure the FreshBooks MCP server in Windsurf?

Edit /.codeium/windsurf/mcpconfig.json or use the Settings UI under Cascade to add the server credentials. Click Refresh in the MCP panel to load the tools.

Q: Can Windsurf and FreshBooks generate new invoices?

No. The available tools like listinvoices and getinvoicedetails are strictly read-only. Your agent analyzes existing billing data rather than creating new financial records.

Q: Why does Windsurf need my FreshBooks account info?

Tools like getaccountinfo and getmyidentity confirm the agent is querying the correct business profile. This prevents cross-contamination if you manage multiple companies.

Q: Does Cascade pull specific client metadata?

Yes. Calling getclientdetails retrieves exact contact information, outstanding balances, and historical data for individual accounts.

Q: How is my FreshBooks financial data secured in Windsurf?

Your raw transaction histories from listexpenses stay local to your environment. The MCP protocol uses a local V8 Isolate Sandbox with ephemeral tokens, meaning Windsurf reads the data in memory and discards it when the session ends.

Let Windsurf Cascade handle your bookkeeping logic by chaining FreshBooks queries automatically.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect FreshBooks MCP to Windsurf

Create your Vinkius account to connect FreshBooks to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup FreshBooks with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

FreshBooks MCP Server inside Windsurf

The `list_invoices` and `list_payments` tools let Cascade read your exact billing state directly from your IDE. You ask for a revenue summary, and the agent pulls the current month's sales data without needing step-by-step instructions. Cascade chains these operations natively. It grabs the uncollected invoices, cross-references them with `get_client_details`, and generates a clear list of who owes you money right in your editor panel.

Audit projects and time entries

Tools like `list_active_projects` and `list_project_tasks` expose your team's current workload to the AI. You can command Windsurf to analyze project scopes against logged hours. The agent uses `list_time_entries` to calculate total time spent on specific client deliverables. It spots discrepancies between estimated and billed hours immediately.

Categorize business expenses

Pulling `list_expenses` gives your AI client access to every recorded transaction. It reads the raw financial data and maps it against `list_expense_categories`. You skip the manual spreadsheet review entirely. Windsurf flags uncategorized receipts and organizes your outgoing cash flow for tax preparation.

Setup guide

Set up FreshBooks MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the FreshBooks MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my FreshBooks payment history." If connected, Cascade will call the FreshBooks tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "freshbooks-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by FreshBooks. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect FreshBooks now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about FreshBooks MCP in Windsurf

Edit `~/.codeium/windsurf/mcp_config.json` or use the Settings UI under Cascade to add the server credentials. Click Refresh in the MCP panel to load the tools.

No. The available tools like `list_invoices` and `get_invoice_details` are strictly read-only. Your agent analyzes existing billing data rather than creating new financial records.

Tools like `get_account_info` and `get_my_identity` confirm the agent is querying the correct business profile. This prevents cross-contamination if you manage multiple companies.

Yes. Calling `get_client_details` retrieves exact contact information, outstanding balances, and historical data for individual accounts.

Your raw transaction histories from `list_expenses` stay local to your environment. The MCP protocol uses a local V8 Isolate Sandbox with ephemeral tokens, meaning Windsurf reads the data in memory and discards it when the session ends.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript