{"_id":"@nightsquawktech/quickbooks-mcp-server","_rev":"2-049af001cd9cd7efdb0541f562c2bc06","name":"@nightsquawktech/quickbooks-mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.0-stage":{"name":"@nightsquawktech/quickbooks-mcp-server","version":"0.0.0-stage","_id":"@nightsquawktech/quickbooks-mcp-server@0.0.0-stage","stub":true,"maintainers":[{"name":"kvrnn","email":"reyeskevin707@gmail.com"}],"dist":{"shasum":"34dfd370ed26aa5b6ed8cc71038664d7d993963e","tarball":"https://registry.npmjs.org/@nightsquawktech/quickbooks-mcp-server/-/quickbooks-mcp-server-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-lbUt24SvykGqxXpmwOZ/EN+jXn7HjFB9rsoCJ0yEgv16hhUmIVv5Cdm4a7n38/Dgy3uylsfLRwDpt3F4+lN0uQ==","signatures":[{"sig":"MEUCIHq6jw59drc5i+ER5cJcOlcpXQMBUuLA7xVGKh/apMaXAiEA1H/hMr8b8a8D7P39X9P4WVIam6u93LvzTiXDU2n4mNw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":360},"_npmUser":{"name":"kvrnn","email":"reyeskevin707@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"_id":"@nightsquawktech/quickbooks-mcp-server@0.1.0","bin":{"quickbooks-mcp-server":"dist/index.js"},"bugs":{"url":"https://github.com/NightSquawk/quickbooks-mcp-server/issues"},"dist":{"shasum":"75ba2bd6b3d09a02ea8d1dc8d57608a0d7185a70","tarball":"https://registry.npmjs.org/@nightsquawktech/quickbooks-mcp-server/-/quickbooks-mcp-server-0.1.0.tgz","fileCount":8223,"integrity":"sha512-5/S4GvNqq9Zqax4NOc9lYVXwe4tTTwQQEZrv5nP9Fk91yj/oALGt8MW7q4HQa17ilkMlvJnqBeO9MPxwJe31MQ==","signatures":[{"sig":"MEYCIQCEAKCWxYw+KexwC6KBzbUnBeDH/r4MDg6x2ja9yGYQKAIhALSeMTe+FykD03fTgjIBDyO/mZvkVtWTEH5J9fTOxMuC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBbvZwVxTWbQaBTFWE/bvU30f31X74Rbnm6ADYunpC3aAiEA/JZowAjZ7xO+gbZcLVlHPVH1hF/TzBI2wVHfkMOdZwc="}],"unpackedSize":16531342},"main":"dist/index.js","name":"@nightsquawktech/quickbooks-mcp-server","type":"module","_from":"file:release/nightsquawktech-quickbooks-mcp-server-0.1.0.tgz","author":{"url":"NightSquawk Tech","name":"Kevin Reyes","email":"hello@nightsquawk.tech"},"engines":{"node":">=22"},"license":"Apache-2.0","scripts":{"auth":"node dist/auth-server.js"},"version":"0.1.0","_npmUser":{"name":"kvrnn","email":"reyeskevin707@gmail.com"},"homepage":"https://github.com/NightSquawk/quickbooks-mcp-server#readme","keywords":["mcp","mcp-server","model-context-protocol","modelcontextprotocol","claude","cursor","ai-agent","llm","quickbooks","quickbooks-online","qbo","accounting","intuit"],"_resolved":"/mnt/data/work/GitHub/NightSquawk/quickbooks-mcp-server/release/nightsquawktech-quickbooks-mcp-server-0.1.0.tgz","_integrity":"sha512-5/S4GvNqq9Zqax4NOc9lYVXwe4tTTwQQEZrv5nP9Fk91yj/oALGt8MW7q4HQa17ilkMlvJnqBeO9MPxwJe31MQ==","repository":{"url":"git+https://github.com/NightSquawk/quickbooks-mcp-server.git","type":"git"},"_npmVersion":"12.2.0","description":"QuickBooks Online MCP server for Claude, Cursor, and AI agents: entity CRUD and 29 financial reports. Fork of intuit/quickbooks-online-mcp-server.","directories":{},"maintainers":[{"name":"kvrnn","email":"reyeskevin707@gmail.com"}],"_nodeVersion":"26.10.0","dependencies":{"zod":"^4.6.7","open":"^9.1.0","dotenv":"^16.4.7","intuit-oauth":"4.2.5-nst.1","node-quickbooks":"2.0.50-nst.1","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"bundleDependencies":["intuit-oauth","node-quickbooks"],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/quickbooks-mcp-server_0.1.0_1793879941015_0.8012845256293845"}}},"time":{"created":"2026-11-05T11:47:47.392Z","modified":"2026-11-05T11:59:01.428Z","0.0.0-stage":"2026-11-05T11:47:47.392Z","0.1.0":"2026-11-05T11:59:01.250Z"},"description":"QuickBooks Online MCP server for Claude, Cursor, and AI agents: entity CRUD and 29 financial reports. Fork of intuit/quickbooks-online-mcp-server.","maintainers":[{"name":"kvrnn","email":"reyeskevin707@gmail.com"}],"readme":"# NightSquawk Tech QuickBooks MCP Server\n\n`@nightsquawktech/quickbooks-mcp-server` is NightSquawk Tech's fork of [Intuit's QuickBooks Online MCP server](https://github.com/intuit/quickbooks-online-mcp-server). It runs locally over stdio for Claude, Cursor, and other MCP clients.\n\nThe server exposes **160 tools**: 131 entity/utility tools and our existing **29 `report_*` tools**. This fork keeps its JSON token store, report interface, catalog work, npm package identity, and publishing workflow while incorporating upstream's expanded tools and fixes.\n\n## Setup\n\n```bash\ngit clone https://github.com/NightSquawk/quickbooks-mcp-server.git\ncd quickbooks-mcp-server\nnpm ci\ncp .env.example .env\n```\n\nCreate an app in the [Intuit Developer Portal](https://developer.intuit.com/), then fill in the static app credentials in `.env`:\n\n```dotenv\nQUICKBOOKS_CLIENT_ID=your_client_id\nQUICKBOOKS_CLIENT_SECRET=your_client_secret\nQUICKBOOKS_ENVIRONMENT=sandbox\nQUICKBOOKS_REDIRECT_URI=http://localhost:8000/callback\n```\n\nRegister the matching redirect URI in your Intuit app. Use credentials for the selected sandbox or production environment.\n\nSandbox authorization supports HTTP loopback `/callback` URLs on `localhost`, `127.0.0.1`, or `[::1]` and listens on the configured port. The default is `http://localhost:8000/callback`; for example, `http://127.0.0.1:8123/callback` uses port 8123. Unsupported callback URLs, including OAuth Playground URLs, are rejected explicitly. Callback URLs must not contain credentials, query parameters, or fragments.\n\n## Authentication\n\n```bash\nnpm run auth\n```\n\nThis explicitly starts browser authorization, even if an existing token can still be refreshed. If no browser is available, the authorization URL is printed to stderr. The OAuth callback validates a random state value and exchanges each authorization code only once.\n\nStatic credentials remain in `.env` or the process environment; explicitly provided process variables take precedence. The server resolves `.env` relative to the installed package, independent of its working directory. It never writes rotating tokens into `.env`.\n\nThe refresh token and realm ID are stored atomically in the gitignored `.qbo-tokens.json`. Access tokens stay in memory and are refreshed ahead of expiry. Concurrent calls share the refresh operation; a rejected refresh can retry a newer token saved by another process.\n\nFor an unattended installation, set `QBO_AUTO_REAUTH=false`. Sandbox tool calls otherwise start browser authorization when needed. Production tool calls fail with reauthorization guidance instead of unexpectedly starting a local browser flow. To authorize production explicitly, configure the registered HTTPS callback and forward it to the local callback server, then run `npm run auth`.\n\n### Existing tokens and custom storage\n\nExisting `QUICKBOOKS_REFRESH_TOKEN` and `QUICKBOOKS_REALM_ID` values are used to initialize the JSON store when it has no saved tokens. Remove the old values from your environment after migration.\n\nFor a read-only package installation or separate company connections, set `QUICKBOOKS_TOKEN_STORE_PATH` to an absolute path to a writable **JSON token file**. Give each company connection its own file and keep it outside source control. Unlike upstream, this setting selects only token storage: it does not replace `.env` or change where static app credentials are loaded. Existing upstream env-format token files must be migrated through the environment variables above, not passed as JSON files.\n\n## MCP client configuration\n\nAfter configuring credentials and authorizing, point your MCP client at the built server:\n\n```json\n{\n  \"mcpServers\": {\n    \"quickbooks\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/quickbooks-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"QBO_AUTO_REAUTH\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## Available tools\n\nEntity tools cover customers, invoices, estimates, bills, vendors, employees, accounts, items, journal entries, bill payments, purchases, payments, sales receipts, credit memos, refund receipts, purchase orders, vendor credits, deposits, transfers, time activities, classes, departments, terms, payment methods, tax entities, company information, preferences, budgets, and attachments. Available operations depend on the entity; tax entities and budgets are read-only.\n\nNotable additions include estimate-to-invoice links, invoice memos/service dates/payment terms, payment reference and multicurrency fields, subaccounts, and bill updates that preserve existing line-level class/tax references. Unsupported top-level parameters produce a warning instead of disappearing silently. Unsupported fields inside closed nested objects, such as invoice line items, are rejected with their field path before execution. Schemas that intentionally accept arbitrary QuickBooks fields remain open.\n\nThe existing `delete_invoice` tool name is retained for compatibility; it voids the invoice and preserves the transaction record.\nThe payment, credit-memo, sales-receipt, refund-receipt, and estimate delete tools perform deletion and are described accordingly.\n\n### Restriction switches\n\nAll tools are enabled by default. Set any of these environment variables to the exact string `true` to suppress that category:\n\n- `QUICKBOOKS_DISABLE_WRITE`: create tools.\n- `QUICKBOOKS_DISABLE_UPDATE`: update tools.\n- `QUICKBOOKS_DISABLE_DELETE`: delete tools.\n\nSet all three for read-only QuickBooks access. Read/search/report tools remain available. These switches restrict QuickBooks operations; PDF output has a separate filesystem setting.\n\n### Attachments and invoice PDFs\n\n`create_attachable` accepts base64 content, an absolute local `file_path`, or an HTTPS `file_url`. Local sources default to home/temp directories; use a semicolon-separated `QUICKBOOKS_ATTACHABLE_BASE_DIR` to select other roots. Credential files, the configured JSON token store (including symlink/hard-link aliases), dot-directories, and the server installation tree are excluded. URL sources validate destinations and redirects.\n\n`get_invoice_pdf` returns base64 by default. Disk output requires `QBO_PDF_OUTPUT_DIR` to name an existing allowed directory. Files are not overwritten unless `overwrite=true`; overwrites replace the output entry atomically without following a final-file symlink or hard link to another file.\n\nPDF downloads stop when the decoded response exceeds 50 MiB, including compressed or chunked responses. Set `QBO_PDF_MAX_BYTES` to a positive integer to change this limit. This bounds the downloaded body; buffering and base64 encoding require additional memory.\n\n### Report tools (29 reports)\n\nRun QuickBooks financial reports via `report_*` tools. All accept optional date range/filter parameters.\n\n**Financial Statements:**\n- `report_balance_sheet` - Balance Sheet\n- `report_profit_and_loss` - Profit and Loss (Income Statement)\n- `report_profit_and_loss_detail` - Profit and Loss with transaction detail\n- `report_trial_balance` - Trial Balance\n- `report_cash_flow` - Statement of Cash Flows\n\n**Sales & Income:**\n- `report_customer_sales` - Sales by Customer\n- `report_item_sales` - Sales by Product/Service\n- `report_customer_income` - Income by Customer\n- `report_department_sales` - Sales by Department\n- `report_class_sales` - Sales by Class\n\n**Customer Reports:**\n- `report_customer_balance` - Customer Balance Summary\n- `report_customer_balance_detail` - Customer Balance Detail\n- `report_aged_receivables` - A/R Aging Summary\n- `report_aged_receivable_detail` - A/R Aging Detail\n\n**Vendor Reports:**\n- `report_vendor_balance` - Vendor Balance Summary\n- `report_vendor_balance_detail` - Vendor Balance Detail\n- `report_aged_payables` - A/P Aging Summary\n- `report_aged_payable_detail` - A/P Aging Detail\n- `report_vendor_expenses` - Expenses by Vendor\n\n**Transaction & Ledger Reports:**\n- `report_transaction_list` - Transaction List\n- `report_transaction_list_with_splits` - Transaction List with Splits\n- `report_transaction_list_by_customer` - Transaction List by Customer\n- `report_transaction_list_by_vendor` - Transaction List by Vendor\n- `report_general_ledger` - General Ledger Detail\n- `report_journal` - Journal Report\n\n**Other:**\n- `report_inventory_valuation_summary` - Inventory Valuation Summary\n- `report_account_list` - Account List Detail\n- `report_trial_balance_fr` - Trial Balance (France only)\n- `report_tax_summary` - Tax Summary (France only)\n\nThe upstream `get_*` report aliases are not registered. Existing clients should continue using `report_*`. Balance sheets with only an `end_date` also send January 1 of that year as `start_date`, following upstream's date-handling correction.\n\n## Development and validation\n\n```bash\nnpm run build\nnpm run lint\nnpm test -- --runInBand\nnpm run test:coverage -- --runInBand\nnpm audit --omit=dev --audit-level=high\n```\n\nCI runs build, lint, and tests on Linux and Windows with Node.js 22. Unit tests mock QuickBooks and do not contact a live company. The catalog JSON and `CATALOG_REFACTOR_PLAN.md` remain development resources; they do not register additional tools.\n\nChanges and releases belong to [NightSquawk/quickbooks-mcp-server](https://github.com/NightSquawk/quickbooks-mcp-server). Intuit's repository is an upstream source only.\n\n## Dependency maintenance and releases\n\nNode.js 22 or later is required. Version 0.1.0 includes NightSquawk-maintained copies of `intuit-oauth@4.2.5-nst.1` and `node-quickbooks@2.0.50-nst.1`. The OAuth patch replaces `query-string` and its vulnerable decoder with native URL parsing, following the approach proposed in [Intuit OAuth PR #218](https://github.com/intuit/oauth-jsclient/pull/218), while retaining callback and encoding compatibility. The QuickBooks client escapes backslashes before quotes in structured query values; its dependency manifest carries the secure versions previously enforced only by root-level overrides.\n\nReadable source, licenses, and provenance are in `vendor/`. Run `npm run vendor:pack` after editing those sources, then explicitly reinstall both archive paths (`npm install ./vendor/intuit-oauth-4.2.5-nst.1.tgz ./vendor/node-quickbooks-2.0.50-nst.1.tgz`) to update their integrity in the lockfile. Development installs use the committed local archives. `npm run package:release` builds a separate publishable archive in `release/`, with those patched packages and their runtime dependencies bundled under exact versions. Publish that archive; a raw `npm pack` of the checkout is not a release artifact. `npm run verify:package` installs the staged release archive in an empty consumer project with an empty npm cache, checks the shipped source and dependency tree, runs its production audit, and verifies all 160 tools over MCP. CI runs this check on Linux and Windows. Repository and packaged-consumer production audits remain blocking for high/critical findings; development-only findings are tracked separately.\n\nRelease tags use `v<package.json version>`. The publishing workflow repeats validation before publishing with npm provenance and OIDC. Initial publication requires an authorized npm publisher; subsequent trusted publishing must be configured for this repository and `.github/workflows/publish.yml`. These local patches can be removed after compatible upstream releases pass the same checks. All changes and releases remain under NightSquawk.\n\nCoverage now includes the full tool surface loaded by startup/MCP contract tests. `jest.config.js` records the broader measured baseline and stricter gates for authentication, token storage, PDF handling, and the report runner. Upstream's historical 100% claim covered a smaller set of imported modules.\n","readmeFilename":"README.md","homepage":"https://github.com/NightSquawk/quickbooks-mcp-server#readme","keywords":["mcp","mcp-server","model-context-protocol","modelcontextprotocol","claude","cursor","ai-agent","llm","quickbooks","quickbooks-online","qbo","accounting","intuit"],"repository":{"url":"git+https://github.com/NightSquawk/quickbooks-mcp-server.git","type":"git"},"author":{"url":"NightSquawk Tech","name":"Kevin Reyes","email":"hello@nightsquawk.tech"},"bugs":{"url":"https://github.com/NightSquawk/quickbooks-mcp-server/issues"},"license":"Apache-2.0"}