---
name: iblai-connect-quickbooks-online
description: "Read and write QuickBooks Online data through the QuickBooks Online Accounting API and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with QuickBooks Online data, or to set up a QuickBooks Online MCP connection on ibl.ai."
metadata:
  kind: guide
---

# QuickBooks Online connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/quickbooks-online — not part of the iblai/vibe repository. Checked against Intuit's documentation on October 20, 2026; test it against your own QuickBooks Online setup before you rely on it.

Cloud accounting software for small businesses. Each QuickBooks Online company holds customers, vendors, invoices, bills, payments, sales receipts, the chart of accounts and financial reports such as Profit and Loss and Balance Sheet.

## Auth & conventions

- **API:** QuickBooks Online Accounting API (REST). REST entity endpoints for one QuickBooks company (realm): create, read, update and query accounting entities such as Customer, Invoice, Bill and Payment, plus a SQL-like query endpoint and financial report endpoints.
- **Base URL:** https://quickbooks.api.intuit.com/v3/company/{realmId}/ (sandbox: https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}/)
- **Access:** Public, self-serve. Developers register an app on the Intuit Developer portal, which issues sandbox keys and a sandbox company for testing; production keys are issued for the same app. The company owner must authorize the app.
- **Auth:** OAuth 2.0 authorization code. The company owner authorizes the app with the com.intuit.quickbooks.accounting scope. The redirect returns an authorization code and the realm ID (Company ID); exchange the code for an access token and refresh token. Every call needs the token and realm ID.
- **Limits:** Production: 500 requests per minute per realm ID and 10 requests per second per realm ID and app; 40 batch requests per minute per realm; a query returns at most 1,000 entities. Throttled calls get HTTP 429; wait 60 seconds before retrying.
- Keep QuickBooks Online credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Query endpoint** — GET /v3/company/{realmId}/query?query=<select statement> reads many entities with a SQL-like SELECT; up to 1,000 entities per response.
- **Customers and vendors** — Customer and Vendor entities: contact details, balances and terms.
- **Invoices and bills** — Invoice and Bill entities with line items, due dates and open balances.
- **Payments** — Payment and sales receipt entities recording money received against invoices.
- **Financial reports** — Report endpoints such as Profit and Loss, Balance Sheet, Cash Flow and General Ledger for a date range.

## Writes

- **Create invoice** — POST /v3/company/{realmId}/invoice creates an invoice for a customer.
- **Create or update customer** — POST to the customer resource creates or updates a customer record.
- **Record payment** — Create a Payment entity applied to open invoices; this changes the books. **Confirm with the user first.**
- **Create bill** — Create a Bill entity for a vendor, adding an accounts payable liability.

## Expose it to an ibl.ai agent (MCP)

Intuit publishes an official MCP server, QuickBooks Online MCP Server (https://github.com/intuit/quickbooks-online-mcp-server). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - QuickBooks Online supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "List every QuickBooks invoice that is more than 30 days past due, with customer and balance"
- "Create an invoice for Acme Corp for 10 hours of consulting at $150 an hour"
- "Pull last quarter's Profit and Loss and compare it with the same quarter last year"
- "Which vendors have unpaid bills due this week?"

## Guardrails

- Holds business financial records and customer and vendor personal data (names, addresses, tax IDs, bank details on payments). Treat as confidential financial data; limit scopes and log writes.
- Request the narrowest QuickBooks Online scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- QuickBooks Online API limits and throttles: https://static.developer.intuit.com/output_html/qbo/docs/learn/limits-and-throttles.html
- Intuit QuickBooks Online MCP server (GitHub): https://github.com/intuit/quickbooks-online-mcp-server
- QuickBooks Online REST API basics: https://developer.intuit.com/app/developer/qbo/docs/learn/rest-api-features
- QuickBooks Online MCP Server: https://github.com/intuit/quickbooks-online-mcp-server
- This connector on ibl.ai: https://ibl.ai/developer/connectors/quickbooks-online
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections