@hlao-mcp/quickbooks

MCP server that wraps the QuickBooks Online Accounting REST API and exposes it as typed tools for HLAO agents.

This package was informed by Intuit's official quickbooks-online-mcp-server reference but is built natively against HLAO's egress conventions: authority-header gating on every write tool, structured ToolError semantics, Streamable HTTP as primary transport, and Zod input validation.

Tools

Read tools:

| Tool | What it does | | ----------------------------- | ------------------------------------------------------------------------- | | get_account_list | List Chart of Accounts entries, paginated. | | get_profit_and_loss_report | Run the Profit and Loss report over a date range. | | get_balance_sheet | Run the Balance Sheet report as of an end date. | | get_vendor_by_id | Fetch a single vendor. | | list_vendors | List vendors, paginated. | | get_customer_by_id | Fetch a single customer. | | list_customers | List customers, paginated. | | get_invoice_by_id | Fetch a single invoice. | | list_invoices | List invoices, paginated, most recent first. | | get_expense_by_id | Fetch a single expense (Purchase entity). | | list_expenses | List expenses, paginated. |

Write tools (require HLAO authority gate):

| Tool | Required passport scope | What it does | | ---------------- | ------------------------------- | ----------------------------------------- | | create_invoice | quickbooks:create_invoice | Create a new invoice with line items. |

All writes return gate_required or gate_denied errors if the HLAO passport is missing or under-scoped. Production deployments wrap this server with @hlao/mcp-gateway; that gateway injects the verified passport from a human-approved review record before the tool issues the upstream call.

Credentials

| Variable | What it is | | -------------------------- | ----------------------------------------------------------------------- | | QUICKBOOKS_CLIENT_ID | Intuit Developer app OAuth client id. Required. | | QUICKBOOKS_CLIENT_SECRET | Intuit Developer app OAuth client secret. Required. | | QUICKBOOKS_REALM_ID | QuickBooks Online Company id (returned during OAuth). Required. | | QUICKBOOKS_ACCESS_TOKEN | Bearer access token from the OAuth dance. Required. | | QUICKBOOKS_REFRESH_TOKEN | Refresh token (the server uses it to rotate access tokens). Required.| | QUICKBOOKS_ENVIRONMENT | production (default) or sandbox. | | QUICKBOOKS_MINOR_VERSION | Intuit minor-version pin. Defaults to 70. |

How to get credentials

1. Create a developer account at developer.intuit.com.
2. Create an app under Dashboard → Apps. Add the com.intuit.quickbooks.accounting scope. Note the Client ID and Client Secret.
3. Use Intuit's OAuth 2.0 Playground (or your own redirect handler) to complete the authorization-code dance against your QuickBooks Online company. Capture the access token, refresh token, and realm id.
4. Store all five in your .env.

The server refreshes the access token automatically on 401. The refresh token rotates every 100 days (Intuit's lifecycle): copy any new refresh token back into .env after a rotation to survive process restarts. Persisting rotated tokens to durable storage is the deployment's responsibility.

Local development

cp .env.example .env
pnpm install
pnpm --filter @hlao-mcp/quickbooks build

HLAO_MCP_HTTP_PORT=3006 node dist/server.js
# or
HLAO_MCP_TRANSPORT=stdio node dist/server.js

For sandbox testing, set QUICKBOOKS_ENVIRONMENT=sandbox and use the sandbox company tokens from your Intuit developer dashboard.