@bossforce.ai/mcp-quickbooks

MCP server for the QuickBooks Online Accounting API. Run queries and read the company profile, and create customers and invoices. Authenticated with OAuth2 using the refresh-token grant; the server exchanges a refresh token for short-lived access tokens itself.

Credentials

| Env | How to obtain | | -------------------------- | ---------------------------------------------------------------------------------------------------- | | QUICKBOOKS_CLIENT_ID | Client ID of the QuickBooks app (provided by the platform as the OAuth client_id). | | QUICKBOOKS_CLIENT_SECRET | Client Secret of the QuickBooks app (the OAuth client_secret). | | QUICKBOOKS_REFRESH_TOKEN | Obtained automatically when you authorize access. Exchanged for access tokens. | | QUICKBOOKS_REALM_ID | The company (realm) id that scopes every API call. Returned alongside the authorization. Not secret. | | QUICKBOOKS_ENV | Set to sandbox to target the QuickBooks sandbox API; defaults to production. Not secret. |

The credentials are read lazily, so the server boots and answers tools/list without them; calls fail with an auth error until they are set. On the first call the client POSTs the refresh token to https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer (grant_type=refresh_token, with client_id:client_secret sent as HTTP Basic auth and the body form-encoded), caches the returned access_token, and re-fetches once on a 401. The API base is https://quickbooks.api.intuit.com/v3/company/{QUICKBOOKS_REALM_ID} (https://sandbox-quickbooks.api.intuit.com when QUICKBOOKS_ENV=sandbox).

Tools

| Tool | Arguments | Returns | | ------------------ | -------------------------------- | -------------------------------------------- | | run_query | query | a QueryResponse with the matching entities | | get_company_info | (none) | the company (organization) profile | | create_customer | display_name, fields? | the created Customer (including its Id) | | create_invoice | customer_id, line, fields? | the created Invoice (including its Id) |

Responses are QuickBooks' native JSON payloads, returned as structuredContent. query uses the QuickBooks SQL-like query syntax (e.g. SELECT * FROM Customer MAXRESULTS 50). QuickBooks has no PUT/PATCH; the create tools POST a full entity. fields uses each entity's field API names.

Develop

pnpm --filter @bossforce.ai/mcp-quickbooks build
pnpm --filter @bossforce.ai/mcp-quickbooks test

Regenerate the tools/list snapshot after an intentional signature change:

UPDATE_SNAPSHOTS=1 pnpm --filter @bossforce.ai/mcp-quickbooks test