npm package: @ilessio/quickbooks-connector
Description: QuickBooks connector launcher for npx users (wraps the Python core).
Latest version: 0.4.0

# 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

![QuickBooks](https://img.shields.io/badge/QuickBooks-2CA01C?style=for-the-badge&logo=quickbooks&logoColor=white)
![Intuit](https://img.shields.io/badge/Intuit-236CFF?style=for-the-badge&logo=intuit&logoColor=white)
![Claude Code](https://img.shields.io/badge/Claude%20Code-1A1A1A?style=for-the-badge&logo=anthropic&logoColor=white)
![Cursor](https://img.shields.io/badge/Cursor-111111?style=for-the-badge&logo=cursor&logoColor=white)
![Codex](https://img.shields.io/badge/Codex-0A0A0A?style=for-the-badge&logo=openai&logoColor=white)

## 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)

```bash
npx @ilessio/quickbooks-connector setup
```

Then configure local env:

```bash
cp .env.example .env
```

```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:

```bash
npx @ilessio/quickbooks-connector auth
```

Connection check:

```bash
npx @ilessio/quickbooks-connector status
```

## Quick Start (Python/uv)

```bash
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:

```bash
uv run qb api endpoints
```

Direct endpoint passthrough:

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

Write with confirmation gate:

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

Reports:

```bash
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)

```json
{
  "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:

```bash
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:

```bash
uv run qb-webhooks
```

Default bind: `127.0.0.1:8090`  
Override:

```bash
QB_WEBHOOK_HOST=0.0.0.0 QB_WEBHOOK_PORT=8090 uv run qb-webhooks
```

Cloudflare tunnel (HTTP/2 fallback):

```bash
./scripts/start_tunnel.sh
```

## Packaging and Release

Local package check:

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

Release bundle generation:

```bash
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