io.github.chrischallPublished by GitHub account chrischallv1.3.1Updated Nov 7, 2026
FreshBooks invoicing for Claude — invoices, clients, estimates, and payments
Local MCP server that connects Claude to FreshBooks, letting it browse and, with confirmation, create invoices, clients, estimates, payments, expenses…
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
MCP server for FreshBooks — invoices, clients, estimates and payments, exposed to Claude as typed tools.
This project was developed and is maintained by AI (Claude Code). Use at your own discretion.
FreshBooks is OAuth2 only — there is no API key and no personal access token, so a one-time browser authorization is required.
https://localhost works and never needs to resolve.FRESHBOOKS_CLIENT_ID and
FRESHBOOKS_CLIENT_SECRET, start it, then call freshbooks_auth_url, open
the URL it returns, approve, and pass the whole URL you land on to
freshbooks_auth_exchange. Its state must match a consent URL the server
issued (valid 15 minutes, single-use), so a bare code, or a redirect URL from
anyone else's authorization, is refused before its code is spent. Local
sessions save the tokens directly to FRESHBOOKS_TOKEN_STORE and return only
a success message. Restart the local MCP server after that message. No token
needs to be copied into chat or configuration. Keep the same app credentials
and store path after restart.authFlow still captures the refresh
token from the exchange response and supplies it through its secret store.
MCP_DATA_DIR identifies this hosted environment. Do not set it for a local
coding-agent connection: hosted mode intentionally returns the token.
Issued states are kept as digests under MCP_DATA_DIR, so a child that is
respawned while the person approves can still complete the login.
The registration's flow must show the person the authorize_url that
freshbooks_auth_url returns. That URL carries the one-time state,
and the exchange refuses any redirect without it. A static consent link
typed into a step description has no state, so every new login or
repair through it fails. Carry authorize_url from the
freshbooks_auth_url step and show it with a step link
(link: {from: 'authorize_url', hosts: ['auth.freshbooks.com']}, mcp-host
2.30.0 or later) on the step that prompts. That prompt must collect the
whole redirect URL, not just its code. Make this change before a
release with state checking reaches the hosted pin. Existing connections
keep refreshing; only new logins and repairs depend on it.skills/freshbooks-curl print tokens.
Run them only in a private terminal, never in an agent's captured terminal.In Claude Desktop, both are optional fields in the extension's settings. If FreshBooks
returns no account_id for the chosen business, invoice/expense writes are refused
(projects and time entries still work) until you set both IDs yourself.
FreshBooks issues a new refresh token on every refresh and immediately invalidates the
old one. This server persists each rotation to FRESHBOOKS_TOKEN_STORE (mode 0600)
before the refresh is considered complete, and prefers the stored token over the
environment value — the stored one has rotated past it.
The login flow also writes a small file of pending consent state digests
(mode 0600, entries expire after 15 minutes). Locally it sits beside the token
store, at <FRESHBOOKS_TOKEN_STORE>.oauth-state.json (by default
~/.freshbooks-mcp/session.json.oauth-state.json). Hosted, it is
$MCP_DATA_DIR/freshbooks-oauth-state.json. It is created on the first
freshbooks_auth_url call, even if the login is never finished, and holds no
tokens.
Two consequences worth knowing:
freshbooks-curl
skill keep separate state files on purpose; sharing one makes them spend each other's
tokens and locks both out.Local sign-in without an environment token binds the private store to the app's
client ID, secret, and redirect URI. Changing those requires a new sign-in.
For existing environment-token setups, the stored rotation still takes precedence;
changing FRESHBOOKS_REFRESH_TOKEN to a new value starts a new token chain.
If you reauthorize locally while FRESHBOOKS_REFRESH_TOKEN is set, keep that same
value configured: the saved login is bound to it. To remove the variable, first
unset it and complete local sign-in again so the store is bound to the app instead.
The local authorization exchange and save use the same lock as refreshes. A refresh
writes only while it holds that lock, so it cannot overwrite a newer login after
releasing the lock.
Restart every local server using the store after reauthorization.
Confirmation-gated means the tool asks you before it writes. A client that can show a
confirmation prompt (Claude Code) shows one with exactly what would be sent. Elsewhere
(claude.ai, Claude Desktop) the first call makes no network call and returns a preview of
the method, path and body that would be sent, plus a single-use confirmToken; only a
repeat call with that token and the same arguments performs the write. A token is refused
if any argument changed since the preview (DRAFT_CHANGED), if it was already used
(TOKEN_REUSED) or once it expires.
Acceptance is an action on the estimate, not a status field: status (int),
display_status and ui_status are computed and read-only, and they disagree with each
other by design (a viewed estimate reads status: 3, display_status: "viewed",
ui_status: "open"). Accepting is PUT estimates/estimates/{id} with
{"estimate": {"action_accept": true}} — see
docs/FRESHBOOKS-API.md for where that shape comes from.
changed: false and no write is sent — acceptance cannot be undone through the API, so
a repeat call must not re-fire it.action_deny, no
estimate.decline webhook. freshbooks_decline_estimate exists only to say so and
point at the alternatives, rather than leave an agent to invent a write that changes
nothing.before / after state and
changed / changedFields, so success is verified against the record rather than
inferred from a 200. changed covers the status fields and the fields that write
actually set, so a successful notes edit reports changed: true even though no status
moves. On freshbooks_send_estimate it describes the record only — emailing an
already-sent estimate moves nothing, and retrying on changed: false would send the
client a second copy.FreshBooks separates the role you hold on a business from the role you hold on an
accounting account. You can own a business that has no accounting account
(account_id: null) while being only a client on the account you can actually see —
in which case reads succeed and every write returns 403 Permission Denied, even though
your OAuth token carries all the :write scopes.
freshbooks_get_identity reports accountRole and businessRole so this is visible up
front. If accountRole is client, the invoicing write tools will not work against that
account — that is an account permission, not a configuration problem.
total counts records you may not be able to read. Expenses reported total: 16
while returning zero rows. List results attach a note when that happens, so it reads
as a permission boundary rather than an empty account.businessId, not accountId, and paginate
under a meta block instead of flat page/pages/total. They also work on a
business with no accounting account at all.FreshBooks hands out three non-interchangeable ids, and using the wrong one returns a bare 404 that reads like a missing record:
Call freshbooks_get_identity first. Full API notes, including the four different error
envelopes, are in docs/FRESHBOOKS-API.md.
skills/freshbooks-curl covers the same API from a
shell with curl + jq, including the OAuth bootstrap and rotation-safe token handling.
MIT
Source: README.md at commit 5a5dbf2
Get the FreshBooks consent URL to authorize this connection. Open it, approve, and you'll land on the redirect URL — pass that whole URL to freshbooks_auth_exchange (its state parameter binds the approval to this server; valid 15 minutes, single-use). Read-only; contacts nothing.
Takes no parameters.
Complete FreshBooks authorization. Local sessions save the credentials privately and return only status; hosted sessions return the refresh token to the host's credential-capture flow. Pass the whole redirect URL: its state must match a consent URL freshbooks_auth_url issued, so a bare code is refused. The code is SINGLE-USE — if this fails, authorize again rather than retrying it.
coderequiredResolve the authenticated FreshBooks user and their identifiers: accountId (alphanumeric, used by accounting and payments endpoints), businessId (integer, used by projects and time tracking) and businessUuid. The three are not interchangeable — using the wrong one returns a 404 rather than a useful error. When the identity belongs to several businesses, `businesses` lists them all; unless FRESHBOOKS_BUSINESS_ID picks one, writes are refused.
Takes no parameters.
Verify credentials and upstream reachability
Resolves the credential the way real tools do, then makes one authenticated request to api.freshbooks.com. Reports which source supplied the credential, whether api.freshbooks.com accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a api.freshbooks.com-side problem'. Read-only; never returns the credential itself. Call this when a real tool fails and you want to know which hop broke.
Takes no parameters.
List invoices for the authenticated FreshBooks account — what clients owe, with each invoice's due date and status. Supports pagination and raw FreshBooks filter params. Returns items plus page/pages/total; view "brief" returns one line per invoice instead.
pageviewsearchper_pageGet a single invoice by its numeric FreshBooks id.
idrequiredList clients for the authenticated FreshBooks account. Supports pagination and raw FreshBooks filter params. Returns items plus page/pages/total.
pagesearchper_pageGet a single client by its numeric FreshBooks id.
idrequiredList estimates for the authenticated FreshBooks account. Supports pagination and raw FreshBooks filter params. Returns items plus page/pages/total.
pagesearchper_pageGet a single estimate by its numeric FreshBooks id.
idrequiredList payments for the authenticated FreshBooks account. Supports pagination and raw FreshBooks filter params. Returns items plus page/pages/total.
pagesearchper_pageGet a single payment by its numeric FreshBooks id.
idrequiredList items for the authenticated FreshBooks account. Supports pagination and raw FreshBooks filter params. Returns items plus page/pages/total.
pagesearchper_pageGet a single item by its numeric FreshBooks id.
idrequiredCreate a client (customer) in FreshBooks. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
emailfnamelnamefieldsconfirmTokenorganizationcurrency_codeCreate an invoice for a client. Created invoices start as drafts. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
linesnotesfieldscustomeridrequiredcreate_dateconfirmTokencurrency_codedue_offset_daysallow_non_client_recipientsUpdate an existing invoice. Only the supplied fields are sent. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Note that changing an invoice out of draft can email it to the client. email_recipients in fields must be addresses on the invoice's client record unless allow_non_client_recipients is set, which is only for addresses the user named themselves.
idrequiredfieldsrequiredconfirmTokenallow_non_client_recipientsRecord a payment against an invoice. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
datenotetypeamountrequiredinvoiceidrequiredconfirmTokenAccept an estimate on behalf of the account, by sending FreshBooks' action_accept on the estimate (PUT estimates/estimates/{id} with {"estimate": {"action_accept": true}}). Acceptance is not reversible through the API — there is no un-accept action. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Idempotent: an estimate already accepted or invoiced is returned unchanged with changed: false and no write is sent. Returns the re-fetched estimate.
idrequiredconfirmTokenNOT SUPPORTED by the FreshBooks API — this tool always fails, and never sends a request. FreshBooks models no declined state for estimates: the status set is draft / sent / viewed / replied / accepted / invoiced, there is no action_deny or action_decline counterpart to action_accept in FreshBooks' own API collection, and there is no estimate.decline webhook event. The tool exists so this answers with the reason instead of a plausible-looking write that changes nothing. Call it to get the alternatives.
idrequiredUpdate an existing estimate. Only the supplied fields are sent; anything omitted is left alone. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Supplying lines REPLACES the whole line set — include each existing line's lineid to keep it. Returns the re-fetched estimate.
idrequiredlinesnotestermsfieldspo_numbercustomeridcreate_datedescriptionconfirmTokenpresentationcurrency_code+2 moreEmail an estimate to the client, by sending FreshBooks' action_email on the estimate (PUT estimates/estimates/{id} with {"estimate": {"action_email": true, …}}). This puts mail in a client's inbox. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Omitting email_recipients lets FreshBooks use the client's own address. email_recipients must be addresses on the estimate's client record unless allow_non_client_recipients is set, which is only for addresses the user named themselves. Returns the re-fetched estimate.
idrequiredbodysubjectconfirmTokenemail_recipientsallow_non_client_recipientsList expenses for the account, newest-first by default. Supports pagination and raw FreshBooks filters (e.g. {"search[categoryid]": 5}). If the response reports a total with no rows, the count includes records this identity cannot read — that is reported in the `note` field rather than looking like an empty account.
pagesearchper_pageGet a single expense by its numeric id.
idrequiredList expense categories, which supply the categoryid used when creating an expense.
pageper_pageRecord an expense. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
datenotesamountrequiredfieldsvendorbillableclientidcategoryidconfirmTokenList projects for the business. Uses businessId (not accountId) and works even when the business has no accounting account.
pageper_pageGet a single project by its numeric id.
idrequiredCreate a project. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
ratetitlerequiredfieldsdue_dateclient_iddescriptionfixed_priceconfirmTokenproject_typeList tracked time entries for the business. The response envelope also carries total_logged and total_unbilled alongside the rows.
pageper_pageLog a time entry. Duration is in SECONDS. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
notebillabledurationrequiredclient_idproject_idservice_idstarted_atrequiredconfirmTokenList services (the billable work types available to projects and time entries).
pageper_pageList any FreshBooks accounting resource by name — the generic reader covering the long tail (taxes, credit notes, invoice profiles, tasks, staff, gateways, bills, bill vendors, bill payments, other income, expense categories) alongside the ones with dedicated tools. Returns items plus page/pages/total. Some resources are gated by plan or account role and will report that rather than returning rows.
pagesearchper_pageresourcerequiredGet a single record from any FreshBooks accounting resource by name and id. Ids are numeric on every resource mapped here; the schema also accepts a string so an id carried around as text still works.
idrequiredresourcerequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
npm install -g @chrischall/freshbooks-mcpFRESHBOOKS_CLIENT_ID=...FRESHBOOKS_CLIENT_SECRET=...FRESHBOOKS_REFRESH_TOKEN=... # optional locally; if set during reauth, keep it setFRESHBOOKS_REDIRECT_URI=https://localhost # optional; must match what you registeredFRESHBOOKS_TOKEN_STORE=~/.freshbooks-mcp/session.json # optionalFRESHBOOKS_BUSINESS_ID=... # optional; required for writes if you belong to several businessesFRESHBOOKS_ACCOUNT_ID=... # optional; with FRESHBOOKS_BUSINESS_ID, confirms its accountId when FreshBooks omits itFRESHBOOKS_REQUEST_TIMEOUT_MS=30000 # optional; per-request deadline for API callsnpm installnpm run buildnpm test