QuickBooks Connector

Production-focused QuickBooks Online connector with:

• full MCP tool surface for AI assistants
• npx launcher for non-Python users
• direct REST passthrough for complete API reach
• strict sandbox-tested accounting workflows

Why this project

• 31 MCP tools exposed and validated
• API passthrough (qb api request) so any QuickBooks Accounting endpoint can be reached
• Dual runtime support: uv and npx
• Strict sandbox validation: customer -> invoice -> payment tested in both CLI and MCP paths

Quick Start (Recommended: npx)

npx @ilessio/quickbooks-connector setup

Then configure local env:

cp .env.example .env

QB_CLIENT_ID=your_client_id_here
QB_CLIENT_SECRET=your_client_secret_here
QB_REDIRECT_URI=http://localhost:8080/callback
QB_ENVIRONMENT=sandbox
QB_DEFAULT_CURRENCY=HKD

Start OAuth:

npx @ilessio/quickbooks-connector auth

Connection check:

npx @ilessio/quickbooks-connector status

Quick Start (Python/uv)

git clone https://github.com/AIFlow-Labs-Limited/quickbooks-connector.git
cd quickbooks-connector
uv sync
uv run qb auth
uv run qb status

API Coverage

Catalog view:

uv run qb api endpoints

Direct endpoint passthrough:

uv run qb api request GET query --params '{"query":"SELECT * FROM Customer MAXRESULTS 5"}'

Write with confirmation gate:

uv run qb api request POST customer --json '{"DisplayName":"Acme Ltd"}'
uv run qb api request POST customer --json '{"DisplayName":"Acme Ltd"}' --confirm

Reports:

uv run qb api report ProfitAndLoss --params '{"start_date":"2026-01-01","end_date":"2026-01-31"}'

MCP + Assistant Integrations

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "@ilessio/quickbooks-connector", "mcp"],
      "env": {
        "QB_CLIENT_ID": "your_client_id_here",
        "QB_CLIENT_SECRET": "your_client_secret_here",
        "QB_REDIRECT_URI": "http://localhost:8080/callback",
        "QB_ENVIRONMENT": "sandbox",
        "QB_DEFAULT_CURRENCY": "HKD"
      }
    }
  }
}

Repository skill layout

• .claude/skills/quickbooks/SKILL.md
• .cursor/skills/quickbooks/SKILL.md
• .codex/skills/quickbooks/SKILL.md

Core Commands

| Command | Description | |---|---| | qb auth | OAuth connect | | qb status | Connection state | | qb api smoke | Core endpoint smoke checks | | qb api endpoints | Entity/report coverage catalog | | qb api request ... | Raw REST passthrough | | qb api report ... | Reports endpoint | | qb api customer-match ... | Find/create customer | | qb api invoice-draft ... | Build invoice payload | | qb api invoice-create ... --confirm | Create invoice | | qb api payment-record ... --confirm | Record payment |

Strict Validation Status

Executed in sandbox:

• CLI strict flow (uv): pass
• CLI strict flow (npx): pass
• MCP strict flow (uv-mcp): pass
• MCP strict flow (npx-mcp): pass
• Tool coverage discovered by MCP: 31/31

Validation artifacts:

• dist/strict-live-sandbox-report.json
• dist/strict-mcp-sandbox-report.json
• dist/strict-manual-sandbox-summary.md

Security and Secrets

Local secret policy:

• .env is local-only and gitignored
• .env.example is safe template only

Quick checks:

git ls-files .env
git check-ignore -v .env

Security scan artifacts:

• dist/security/security-report.md
• dist/security/pip-audit.json
• dist/security/npm-audit.json
• dist/security/bandit.json

Webhooks and Tunnel

Webhook server:

uv run qb-webhooks

Default bind: 127.0.0.1:8090
Override:

QB_WEBHOOK_HOST=0.0.0.0 QB_WEBHOOK_PORT=8090 uv run qb-webhooks

Cloudflare tunnel (HTTP/2 fallback):

./scripts/start_tunnel.sh

Packaging and Release

Local package check:

npm pack --pack-destination dist
npx --yes --package=./dist/ilessio-quickbooks-connector-0.4.0.tgz quickbooks-connector status

Release bundle generation:

uv run python scripts/package_release.py

More details:

• docs/marketplace-release.md
• docs/production-hardening.md

Requirements

• Python 3.13+
• uv
• Node.js 18+ (for npx launcher)
• QuickBooks Online + Intuit Developer app

License

MIT