qb-auto — QuickBooks MCP Server

MCP (Model Context Protocol) server that gives Claude Code native tools for QuickBooks Online automation.

Replaces 50K-token browser_snapshot round-trips with targeted DOM extraction (~200-500 tokens) and compound Playwright actions that complete entire workflows in one tool call.

Tools

Tool	Description
qb_page_state	Check current page/dialog state (~50 tokens)
qb_list_invoices	List all visible invoices with optional customer filter
qb_invoice_state	Inspect an open invoice form (line items, totals)
qb_receive_payment	Record a payment (navigate → fill → save → confirm)
qb_create_invoice	Create a new invoice with line items
qb_delete_line_item	Delete a line from an existing invoice
qb_edit_payment_amount	Edit an existing payment amount
qb_batch_receive_payments	Record multiple payments in sequence
qb_report	Run any QBO report (30+ report types) with date range options
qb_report_pnl	Profit & Loss (income statement)
qb_report_balance_sheet	Balance Sheet (assets, liabilities, equity)
qb_report_ar_aging	A/R Aging Summary (who owes, how overdue)
qb_report_customer_balance	Customer Balance Summary
qb_report_open_invoices	Open (unpaid) Invoices
qb_report_vendor_balance	Vendor Balance Summary

Token Savings

Workflow	Before (snapshots)	After (MCP)	Savings
Receive Payment	~290K tokens	~13K tokens	95%
Create Invoice	~350K tokens	~18K tokens	95%
Full session (5 ops)	~500K tokens	~45K tokens	91%

Setup

Prerequisites

• Python 3.10+
• mcp and playwright packages
• Chrome running with remote debugging: google-chrome --remote-debugging-port=9222

Install

pip install mcp playwright
playwright install chromium

Register with Claude Code

Add to ~/.mcp.json:

{
  "mcpServers": {
    "quickbooks": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/qb-auto/server.py"]
    }
  }
}

Configuration

The server connects to Chrome via CDP (Chrome DevTools Protocol) on port 9222 by default. Set the CDP_PORT variable in server.py if using a different port.

Architecture

• Extractors: JavaScript functions injected via page.evaluate() that return compact JSON from QB's DOM using ARIA selectors
• Actions: Complete Playwright workflows using getByRole() and getByLabel() — ARIA-stable selectors that survive QB page reloads
• Playbook: PLAYBOOK.md contains the full reference for manual use with browser_evaluate/browser_run_code

Files

File	Purpose
server.py	MCP server with 15 tools
extractors.js	Standalone JS extractor functions (reference)
actions.js	Playwright action templates (reference)
PLAYBOOK.md	Quick reference for manual browser automation

How It Works

1. Claude calls qb_receive_payment(invoice_num="6865", amount="22500", method="ACH")
2. Server connects to your Chrome browser via CDP
3. Navigates to QB invoices, finds the invoice, opens payment dialog
4. Fills method, amount, saves, handles confirmations
5. Returns compact JSON result (~200 tokens)

No browser snapshots. No 50K token pages. One tool call = one complete operation.

License

MIT