# How to connect FreshBooks to Hermes Agent (no API keys) > Connect FreshBooks to Hermes Agent with ClawLink: 10 tools via hosted OAuth, no API keys, no config files. The AI Overview already quotes this page's install flow; here is the setup it describes. Web version: https://claw-link.dev/hermes/freshbooks Most guides for giving Hermes Agent FreshBooks access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical FreshBooks setup: pair once in the browser and your always-on Hermes agent can act on FreshBooks for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself. **Start here — paste this into Hermes to set up ClawLink:** > Set up ClawLink for Hermes and tell me when it's ready. > 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable` > 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait. > 3. I'll approve it in my browser, then reply "approved". > 4. When I say approved, finish setup: `hermes clawlink finish` > 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready. ## Setup It takes three steps to connect Hermes to FreshBooks. 1. **Install ClawLink** — add the plugin to Hermes Agent once. 2. **Connect FreshBooks** — one-click OAuth in the ClawLink dashboard. 3. **Use it from chat** — ask Hermes Agent in plain English. **Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead: ```bash npx -y @useclawlink/cli login # sign in via browser — no API key to paste npx -y @useclawlink/cli connect freshbooks # connect FreshBooks (browser OAuth) npx -y @useclawlink/cli actions freshbooks # list available actions npx -y @useclawlink/cli run freshbooks --input '' # execute (add --confirm for writes) ``` ### Install by command The prompt above walks Hermes through this. By hand, it is four commands and a browser approval: ```bash hermes plugins install ClawLink-HQ/hermes-plugin --enable hermes clawlink begin # prints an approval link — open it and approve hermes clawlink finish # after approving in the browser hermes clawlink test ``` Then connect FreshBooks in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys. Verify the connection by asking Hermes: > List my businesses with freshbooks_list_businesses, then list the clients in the active business with freshbooks_list_clients. Summarize them by billing status and flag any with missing contact details. ### Using a different agent? The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI: ```bash npx -y @useclawlink/cli login ``` `login` opens the same browser approval and stores a credential locally. Once FreshBooks is connected in the dashboard, that agent calls the same 10 FreshBooks tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent). ## FreshBooks MCP for Hermes Looking for a FreshBooks MCP server for Hermes Agent? ClawLink connects FreshBooks to Hermes Agent and exposes 10 FreshBooks tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw FreshBooks integration](https://claw-link.dev/openclaw/freshbooks) runs on the same hosted FreshBooks provider and the same 10 tools; OpenClaw installs ClawLink through a ClawHub skill instead of the Hermes pairing commands. This is the page Google's AI Overview already quotes for this question: the s01 answer walks the exact install flow below and cites this page as its first reference. The steps are the same ones every sibling page in this cluster uses, deliberately, because keeping the command copy identical is what keeps a cited flow correct. Pair Hermes with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then `hermes clawlink begin` and `hermes clawlink finish`, connect FreshBooks from the dashboard, and the 10 tools below are callable from chat. The alternative the same search results teach is a Composio CLI install plus an `mcp_servers:` block hand-edited into `~/.hermes/config.yaml`; this page's route has none of that. The toolkit is deliberately small, and it is read-heavy: businesses, clients, projects, journal entries, and webhooks, with webhook management as the main write. ## What the Hermes Agent FreshBooks integration can do 10 FreshBooks tools are ready for Hermes Agent once the account is connected. The 9 below are the ones people reach for most; your agent can call all 10. ### 9 of 10 FreshBooks tools for Hermes | Tool | What it does | |---|---| | **Create webhook** `freshbooks_create_webhook` | Register a new webhook callback for a FreshBooks account | | **Get business users** `freshbooks_get_business_users` | Get staff identities and members for a FreshBooks business | | **List businesses** `freshbooks_list_businesses` | List all businesses associated with the authenticated user | | **List clients** `freshbooks_list_clients` | List all clients for a FreshBooks account | | **List journal entries2** `freshbooks_list_journal_entries2` | List all journal entries for a FreshBooks business account | | **List projects** `freshbooks_list_projects` | List all projects associated with a FreshBooks business | | **List webhooks** `freshbooks_list_webhooks` | List all webhook callbacks registered for a FreshBooks account | | **Update webhook** `freshbooks_update_webhook` | Update or verify a FreshBooks webhook callback | | **Register as a new user** `freshbooks_register_as_a_new_user` | Register a new user account in FreshBooks | ## Example prompts **Client overview** > List my businesses with freshbooks_list_businesses, then list the clients in the active business with freshbooks_list_clients. Summarize them by billing status and flag any with missing contact details. **Project progress** > List the projects in my active business and tell me which ones have no recent journal entries. Use freshbooks_list_journal_entries2 only for the projects I care about, not a full sweep. **Who has access** > Call freshbooks_get_business_users and tell me which users have access to each business I own and what roles they hold. **Webhook review** > List my webhooks with freshbooks_list_webhooks and tell me which events they subscribe to and when each was last called. Do not create or update any webhook without my approval. ## How the FreshBooks tools behave What the 10 tools actually cover, from the live schemas, so a prompt asks for things the toolkit can do. - **The toolkit is read-heavy by design.** Businesses, clients, projects, journal entries, and business users are all readable; the only writes are webhook creation and updates. - **There is no invoice tool.** No create-invoice or list-invoices tool exists in this toolkit, and an agent that pretends otherwise will invent a call. The page says so explicitly so the agent says "I cannot" instead. - **`freshbooks_register_as_a_new_user` is a real exposed action.** It is the odd one out on a business page, but it is genuinely part of the toolkit; treat it as an auth-shaped utility rather than a bookkeeping action. - **Everything is business-scoped.** Every read happens inside a business, so the first call is `freshbooks_list_businesses` and subsequent calls must carry the right business context or they 403 role-gated. - **Webhooks are the write surface.** `freshbooks_create_webhook` and `freshbooks_update_webhook` manage callbacks; updating or deleting one changes what your systems receive, so they deserve an explicit go-ahead in the prompt. ## ClawLink vs. building it yourself The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want FreshBooks working from chat. | | Manual | ClawLink | |---|---|---| | **Connection flow** | Register a FreshBooks app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect FreshBooks through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. | | **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for FreshBooks. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. | | **Agent usability** | You still need to expose the right FreshBooks actions to the runtime in a format your agent can reliably use. | 10 tools for FreshBooks are already exposed through ClawLink, so the agent can read and act from chat immediately. | ## ClawLink vs. Composio Composio also exposes FreshBooks to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect FreshBooks in the browser, and the 10 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison. ### Hermes paired but still can't use FreshBooks Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`. ### Connection succeeds but no tools appear Reconnect FreshBooks from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded. ### "Tool schema not loaded yet" error when calling FreshBooks tools FreshBooks tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every FreshBooks call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again. ### FreshBooks returns 403 or "permission denied" on one action while others work Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs. ### FreshBooks returns 403 although the account is connected Role-gating is the taught cause first: FreshBooks OAuth scopes are tied to the connected user's role, so a client-only login or a user without membership in the business the call targets gets 403 for that business's data while other calls succeed. Check which user this connection acts as before touching anything else. The second cause is the argument: an invented or copied-from-an-example client or project id returns a permission-shaped error because FreshBooks hides what the account cannot see. The advice search results give, deleting old tokens or cache and re-authenticating, assumes a token file exists; in a hosted flow there is no file, and reconnecting from the dashboard is the only re-auth that exists. Ask the agent to diagnose it: ```text Call freshbooks_list_businesses and freshbooks_get_business_users. Tell me which business this connection can see and which user it acts as, then quote the exact error from the failed call. Do not retry it yet. ``` ### FreshBooks tools are missing, or one tool name is not found The search-result fix for this symptom is client-cache cleanup: delete `mcp-cache.json`, check stdio versus HTTP transport, or run a `curl` tools/list probe. Those are local-client remedies, and there is no local client here. If Hermes shows no FreshBooks tools at all, confirm the plugin installed with `--enable`, that both pairing commands ran, and that FreshBooks shows as connected in the dashboard, then start a fresh chat. If most tools work and a single name fails, the name is wrong rather than missing, and the error lists the closest real ones. One timing case is unique to this setup: schemas load on demand, so the opening FreshBooks call in a fresh session can arrive before the catalog and needs one retry. Ask the agent to diagnose it: ```text List the FreshBooks tools you actually have access to. If there are none, say so plainly. If there are, tell me which one lists businesses and use that exact name. ``` ### OAuth finished in the browser but the account is still missing Try reconnecting FreshBooks and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete. ### Is there a Hermes Agent FreshBooks integration? Yes. ClawLink is the fastest way to connect Hermes to FreshBooks: link your FreshBooks account once in the browser and Hermes Agent can call the FreshBooks API through 10 ready-made tools — no custom code or token handling. ### How do I connect FreshBooks to Hermes with ClawLink? Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect FreshBooks in the dashboard and Hermes can use it from the next message — no config files or API keys to manage. ### How long does it take to connect FreshBooks to Hermes Agent? About two minutes. Sign in, click Connect next to FreshBooks in the dashboard, authenticate, and Hermes Agent can use it from the next chat message. ### Why use ClawLink instead of wiring FreshBooks up myself? The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want FreshBooks working from chat. ### Does FreshBooks have an official MCP server? Not one the market has found: search results repeat "FreshBooks does not provide an official first-party MCP server" across several AI Overviews, and the answers recommend third-party toolkits and GitHub wrappers instead. This page's "FreshBooks MCP for Hermes" section is the hosted equivalent of that missing server: the same FreshBooks API, exposed as tools, with the auth handled by ClawLink. If what you want is a self-hosted MCP server you run yourself, that remains a community-server task; if what you want is FreshBooks tools callable from Hermes chat, this page's setup is the route without a server. ### What can the agent do with only 10 tools? The honest answer: read most of the account, write very little. The reads cover businesses, clients, projects, journal entries, business users, and webhooks; the writes are webhook registration and updating webhooks, plus `freshbooks_register_as_a_new_user`. There is deliberately no invoice creation tool in this toolkit, so an agent asked to create an invoice should say it cannot rather than invent a call. For the reading patterns agents are actually useful for, summarizing client lists, project progress, and journal activity, the toolkit is exactly sized. ### Why is the agent failing with 403 when the connection works? FreshBooks scopes are role-gated, and this is the taught cause: a connected account with client-only login or without membership in the business the tool targets fails with 403 on that business's data, while other calls keep working. The fix is to connect a user who belongs to the business the agent should work in. Note the difference from the usual advice, which is to delete old tokens or cache and re-authenticate: there is no token file or cache in a hosted flow, so that advice does not apply here. Reconnecting from the dashboard re-issues the grant if a role changed after the connection was made. ### Is it safe to connect FreshBooks to an AI agent? The risk surface is small because the toolkit is small: the tool table on this page is the complete set of operations the agent can invoke, the OAuth grant is re-issuable, and revocation from the dashboard is immediate. The engine-taught advice for this provider is token and scope hygiene, which assumes you hold tokens; in this flow the tokens are held server-side and never shown to the agent. The user-side lever that matters is which account you connect, since FreshBooks scopes are role-gated and a connected user with broader access gives the agent broader reach. ### Hermes paired but still can't use FreshBooks Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`. ## Related - [Connect Zoho Invoice](https://claw-link.dev/hermes/zoho-invoice) — Create and send invoices, track payments, and manage billing - [Square](https://claw-link.dev/hermes/square) — Process payments and manage POS - [Hermes Sevdesk integration](https://claw-link.dev/hermes/sevdesk) — sevDesk is an online accounting software designed for small businesses and freelancers, offering features like invoicing, expense management, and financial reporting.