{
  "markdown": "# QuickBooks MCP Server\n\nAn MCP server for QuickBooks Online — built for bookkeepers, CFOs, and accountants who use AI assistants in their daily workflow.\n\nAsk your AI assistant to pull a P&L report, create a journal entry, or investigate an account balance — using plain language, not API payloads.\n\n## Why This Server?\n\nIntuit provides an [official MCP server](https://github.com/intuit/quickbooks-online-mcp-server) that's a solid starting point for developers exploring the QuickBooks API. This server takes a different approach: it's designed for **financial professionals working in production books**.\n\n### Use natural language, not internal IDs\n\nIntuit's server requires QuickBooks internal IDs for every reference — you need to look up a vendor's ID before creating a bill. This server resolves names automatically:\n\n```\n\"Create a bill for PG&E, $450 to Utilities, dated 2025-01-15\"\n→ Vendor, account, and department names are resolved automatically\n```\n\n### Financial reports built in\n\nThis is the only QuickBooks MCP server with report tools. Pull a P&L, Balance Sheet, or Trial Balance — broken down by month, department, or class — without leaving your AI conversation.\n\n### Safe by default\n\nEvery create and edit operation defaults to **draft/preview mode**. You see exactly what will be written to your books before committing. No accidental journal entries or misclassified expenses.\n\n### One query tool instead of dozens\n\nInstead of separate search tools for each entity type, a single SQL-like `query` tool works across all QuickBooks entities. AI assistants write SQL naturally, and QuickBooks validates it — no field whitelists to maintain.\n\n```\n\"SELECT * FROM Purchase WHERE TxnDate >= '2025-01-01' AND TxnDate <= '2025-01-31'\"\n```\n\n### Production-ready credential management\n\nStore credentials locally for personal use, or in AWS Secrets Manager for shared environments. OAuth tokens refresh automatically and persist across sessions.\n\n### At a glance\n\n| | Intuit Official | This Server |\n|--|-----------------|-------------|\n| **Audience** | Developers exploring the API | Bookkeepers, CFOs, accountants |\n| **Name resolution** | Requires internal QB IDs | Resolves names automatically |\n| **Financial reports** | None | P&L, Balance Sheet, Trial Balance |\n| **Write safety** | Executes immediately | Draft preview by default |\n| **Query approach** | Entity-specific search tools | SQL-like queries across all entities |\n| **Credentials** | Local `.env` file | Local file or AWS Secrets Manager |\n| **Distribution** | Clone from GitHub | `npx quickbooks-mcp` |\n\n## Prerequisites\n\n- **QuickBooks Developer Account**: Register at [developer.intuit.com](https://developer.intuit.com)\n- **Node.js 18+**\n\n## Installation Options\n\nChoose the setup that fits your use case:\n\n| Setup | Best For |\n|-------|----------|\n| [NPM Install](#option-1-npm-install) | Quick setup, using your own QuickBooks app |\n| [Local Checkout](#option-2-local-checkout) | Development, customization |\n| [AWS Mode](#option-3-aws-mode) | Shared/production environments |\n\n---\n\n## Option 1: NPM Install\n\nThe simplest way to get started. Credentials are stored locally on your machine.\n\n### 1. Create a QuickBooks App\n\n1. Go to [developer.intuit.com](https://developer.intuit.com) and sign in\n2. Create a new app (or select an existing one)\n3. Go to \"Keys & credentials\"\n4. Note your **Client ID** and **Client Secret**\n5. Under \"Redirect URIs\", add: `https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl`\n\n### 2. Add to Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"quickbooks\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"quickbooks-mcp\"]\n    }\n  }\n}\n```\n\n### 3. Configure Credentials\n\nCreate `~/.quickbooks-mcp/credentials.json`:\n\n```json\n{\n  \"client_id\": \"your_client_id\",\n  \"client_secret\": \"your_client_secret\"\n}\n```\n\n### 4. Authenticate\n\nOnce Claude Code is running, use the `qbo_authenticate` tool:\n\n1. Call `qbo_authenticate` with no arguments to get an authorization URL\n2. Open the URL in your browser and authorize the app\n3. Copy the `code` and `realmId` from the redirect URL\n4. Call `qbo_authenticate` again with the authorization code and realm ID\n\nYour OAuth tokens will be saved and automatically refreshed.\n\n---\n\n## Option 2: Local Checkout\n\nFor development or customization.\n\n### 1. Create a QuickBooks App\n\nFollow the same steps as Option 1 above.\n\n### 2. Clone and Build\n\n```bash\ngit clone https://github.com/laf-rge/quickbooks-mcp.git\ncd quickbooks-mcp\nnpm install\nnpm run build\n```\n\n### 3. Add to Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"quickbooks\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/quickbooks-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### 4. Configure Credentials\n\nCreate `~/.quickbooks-mcp/credentials.json` with your client credentials (same as Option 1), then run `qbo_authenticate` to complete the OAuth flow.\n\n---\n\n## Option 3: AWS Mode\n\nFor shared or production environments. Stores credentials in AWS Secrets Manager.\n\n### 1. Create AWS Resources\n\n**Create the secret in Secrets Manager:**\n\n```bash\naws secretsmanager create-secret \\\n  --name prod/qbo \\\n  --secret-string '{\n    \"client_id\": \"your_client_id\",\n    \"client_secret\": \"your_client_secret\",\n    \"access_token\": \"your_access_token\",\n    \"refresh_token\": \"your_refresh_token\",\n    \"redirect_url\": \"https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl\"\n  }'\n```\n\n**Store Company ID in SSM Parameter Store:**\n\n```bash\naws ssm put-parameter \\\n  --name /prod/qbo/company_id \\\n  --value \"your_company_id\" \\\n  --type SecureString\n```\n\n### 2. Configure the Server\n\nCreate a `.env` file in the quickbooks-mcp directory:\n\n```bash\nQBO_CREDENTIAL_MODE=aws\nAWS_REGION=us-east-2\nQBO_SECRET_NAME=prod/qbo\nQBO_COMPANY_ID_PARAM=/prod/qbo/company_id\n```\n\n> **Note**: Due to a [known Claude Code bug](https://github.com/anthropics/claude-code/issues/1254), environment variables from `.mcp.json` are not reliably passed to MCP servers. The `.env` file workaround is required.\n\n### 3. Add to Claude Code\n\n```json\n{\n  \"mcpServers\": {\n    \"quickbooks\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/quickbooks-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### 4. IAM Permissions\n\nThe server needs these AWS permissions:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"secretsmanager:GetSecretValue\",\n        \"secretsmanager:PutSecretValue\"\n      ],\n      \"Resource\": \"arn:aws:secretsmanager:*:*:secret:prod/qbo*\"\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\"ssm:GetParameter\"],\n      \"Resource\": \"arn:aws:ssm:*:*:parameter/prod/qbo/*\"\n    }\n  ]\n}\n```\n\n---\n\n## Inline Output Mode\n\nBy default, large responses (reports, query results) are written to `/tmp` files and the server returns a file path. This works well for Claude Code in terminal environments but breaks in **Claude Desktop** and **plugin environments** where the model cannot read from `/tmp`.\n\nSet `QBO_INLINE_OUTPUT=true` to return all responses inline instead.\n\n**Option A — via `.env` file** (recommended for local checkout):\n\nCreate a `.env` file in the quickbooks-mcp directory:\n\n```bash\nQBO_INLINE_OUTPUT=true\n```\n\n**Option B — via `.mcp.json` env block** (recommended for NPM install):\n\n```json\n{\n  \"mcpServers\": {\n    \"quickbooks\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"quickbooks-mcp\"],\n      \"env\": {\n        \"QBO_CREDENTIAL_MODE\": \"local\",\n        \"QBO_INLINE_OUTPUT\": \"true\"\n      }\n    }\n  }\n}\n```\n\n> **Note**: Due to a [known Claude Code bug](https://github.com/anthropics/claude-code/issues/1254), environment variables from `.mcp.json` are not reliably passed to MCP servers in some configurations. If Option B doesn't work, use the `.env` file workaround.\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `QBO_CREDENTIAL_MODE` | `local` | Credential storage: `local` or `aws` |\n| `QBO_CLIENT_ID` | - | QuickBooks app Client ID (local mode) |\n| `QBO_CLIENT_SECRET` | - | QuickBooks app Client Secret (local mode) |\n| `QBO_CREDENTIAL_FILE` | `~/.quickbooks-mcp/credentials.json` | Custom credential file path. A leading `~` is expanded to your home directory, so it works in an MCP client's JSON `env` block where no shell is present to expand it. |\n| `QBO_INLINE_OUTPUT` | `false` | Return responses inline instead of writing to `/tmp` files. Required when using Claude Desktop or plugin environments where file-based output is not accessible to the model. |\n| `QBO_SANDBOX` | `false` | Use QuickBooks sandbox environment. Also switches the \"View in QuickBooks\" deep links to `app.sandbox.qbo.intuit.com` so they cannot open the production company. |\n| `AWS_REGION` | `us-east-2` | AWS region (aws mode) |\n| `QBO_SECRET_NAME` | `prod/qbo` | Secrets Manager secret name (aws mode) |\n| `QBO_COMPANY_ID_PARAM` | `/prod/qbo/company_id` | SSM parameter path (aws mode) |\n\n---\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| **Setup** | |\n| `qbo_authenticate` | Set up OAuth credentials (local mode only) |\n| `get_company_info` | Get connected company information |\n| **Query & Reports** | |\n| `query` | Run SQL-like queries against any QuickBooks entity |\n| `list_accounts` | List chart of accounts with filtering |\n| `get_profit_loss` | Profit & Loss report (by month, department, class, etc.) |\n| `get_balance_sheet` | Balance Sheet report |\n| `get_trial_balance` | Trial Balance report (`flags: true` adds a close-review pass for wrong-side and uncategorized/suspense balances) |\n| `get_report` | Any of 24 other QuickBooks reports — A/R and A/P aging, customer and vendor balances, transaction lists, general ledger, journal, sales by customer/item/class/department, cash flow, and the detail variants |\n| `query_account_transactions` | All transactions affecting a specific account (13 posting entity types, paginated, optional sub-account rollup; see `docs/entity-coverage.md` for limits) |\n| `account_period_summary` | Period summary for an account (opening/closing balance, debits, credits, count) |\n| **Journal Entries** | |\n| `create_journal_entry` | Create a journal entry (validates debits = credits; lines take `entity_name`/`entity_type`) |\n| `get_journal_entry` | Fetch a journal entry by ID |\n| `edit_journal_entry` | Modify an existing journal entry |\n| **Bills** | |\n| `create_bill` | Create a vendor bill (lines take `customer_name`) |\n| `get_bill` | Fetch a bill by ID |\n| `edit_bill` | Modify an existing bill |\n| **Expenses** | |\n| `create_expense` | Create an expense (Cash, Check, or Credit Card; payee may be a vendor, customer, or employee) |\n| `get_expense` | Fetch an expense by ID |\n| `edit_expense` | Modify an existing expense |\n| **Sales Receipts** | |\n| `create_sales_receipt` | Create a sales receipt with item lines |\n| `get_sales_receipt` | Fetch a sales receipt by ID |\n| `edit_sales_receipt` | Modify an existing sales receipt |\n| **Invoices** | |\n| `create_invoice` | Create an invoice with item lines (customer required) |\n| `get_invoice` | Fetch an invoice by ID |\n| `edit_invoice` | Modify an existing invoice |\n| **Deposits** | |\n| `create_deposit` | Create a bank deposit (lines take `entity_name`/`entity_type`) |\n| `get_deposit` | Fetch a deposit by ID |\n| `edit_deposit` | Modify an existing deposit (lines take `entity_name`/`entity_type`) |\n| **Vendor Credits** | |\n| `create_vendor_credit` | Create a vendor credit (lines take `customer_name`) |\n| `get_vendor_credit` | Fetch a vendor credit by ID |\n| `edit_vendor_credit` | Modify an existing vendor credit |\n| **Bill Payments** | |\n| `create_bill_payment` | Pay bills and apply vendor credits (the QBO \"check\" / pay-bills flow) |\n| `receive_payment` | Record a customer payment against open invoices (A/R counterpart to `create_bill_payment`); each line defaults to the invoice's open balance |\n| `create_transfer` | Move money between two of the company's own accounts (bank↔bank, credit-card paydown) |\n| `get_bill_payment` | Fetch a bill payment by ID; flags unapplied amounts |\n| **Delete** | |\n| `delete_entity` | Delete any transaction (journal entry, bill, invoice, deposit, sales receipt, expense, vendor credit, bill payment) |\n\n### Naming Vendors, Customers, and Employees\n\nEvery write tool that can attribute a line or a header to a name list accepts a\nname and resolves it to an ID, the same way `account_name` and\n`department_name` do. Which parameter you get depends on what QuickBooks will\nactually store there:\n\n| Parameter | Where it applies | Accepts |\n|-----------|------------------|---------|\n| `entity_name` + `entity_type` | `create_deposit` / `edit_deposit` lines, `create_journal_entry` / `edit_journal_entry` lines, `create_expense` / `edit_expense` header payee | Vendor, Customer, or Employee. `entity_type` defaults to `Vendor`. |\n| `customer_name` | `create_bill` / `edit_bill`, `create_expense` / `edit_expense`, `create_vendor_credit` / `edit_vendor_credit` lines | Customer only — QuickBooks stores a `CustomerRef` on these lines and has no vendor or employee option. |\n| `vendor_name` | `create_bill`, `create_vendor_credit`, `create_bill_payment` headers | Vendor only. |\n| `customer_name` (header) | `create_invoice`, `create_sales_receipt` | Customer only. Their item lines have no per-line entity. |\n\nEach also has an `_id` form (`entity_id`, `customer_id`) if you already know the\ninternal ID. On edit tools, the rule for line parameters is:\n\n- **omit** the parameter and a line addressed by `line_id` keeps the entity it\n  already has;\n- **name** one and it is set or replaced;\n- **pass an empty string** (`entity_name: \"\"`) and it is cleared.\n\nSee [`docs/quickbooks-api-limitations.md`](docs/quickbooks-api-limitations.md#entity-attribution-is-four-different-fields)\nfor the underlying QBO field shapes, which are not uniform.\n\n### Parameter Names Are Enforced\n\nArguments are checked against the schema each tool advertises, before anything\nruns. An unknown parameter is an error that names the closest valid one, a\nmissing required parameter is an error, and an `edit_*` call with no field to\nchange is an error rather than a write that reports success.\n\nThe alternative is silence. A handler reads the parameters it knows about, so a\nmisspelled one is simply absent: a create call that puts the date under the\nwrong key posts on today's date, an as-of report asked for a date range returns\ntoday's balances, and an edit whose fields are all misspelled comes back\n\"updated successfully\" having changed nothing. None of those raise anything for\nthe caller to notice.\n\nRelatedly, when QuickBooks accepts an update without advancing the record's\n`SyncToken` — meaning the payload matched what was already stored — the edit\ntools report no change instead of success.\n\n---\n\n## Token Refresh\n\nThe server automatically refreshes OAuth tokens on each request and persists them back to your credential store (local file or AWS Secrets Manager).\n\n---\n\n## Development\n\n```bash\nnpm run dev      # Run in development mode\nnpm run build    # Build\nnpm run typecheck # Type check\nnpm test         # Run the test suite\n```\n\nTests live in `tests/`, mirroring `src/`. They are TypeScript, compiled by\n`tsconfig.test.json` into `dist-test/` and run by Node's built-in test runner —\nno test framework dependency. Type errors in a test are build failures, so a\ntest referencing a renamed export fails loudly rather than silently skipping.\nAnything needing a QuickBooks client passes a hand-written stand-in covering\njust the calls under test, so the suite runs offline with no credentials.\n\n---\n\n## Troubleshooting\n\n### \"QuickBooks credentials not configured\"\n\nRun the `qbo_authenticate` tool to set up OAuth credentials (local mode only).\n\n### \"Authorization code expired\"\n\nAuthorization codes are only valid for a few minutes. Start the OAuth flow again.\n\n### Token refresh fails\n\n- Check that your refresh token hasn't expired (~100 days)\n- Verify your client credentials are correct\n- Try re-authenticating with `qbo_authenticate`\n\n### AWS credential errors\n\n- Ensure `.env` file has `QBO_CREDENTIAL_MODE=aws`\n- Check your AWS credentials and permissions\n- Verify the secret and parameter names match your configuration\n",
  "bytes": 16257,
  "sha": "07a0d42f1ff8a0c8b8b0200f3caeec1c04e01df50c5738a3620e3fcc2c55eeeb",
  "repo_slug": "laf-rge/quickbooks-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_laf_rge_quickbooks_mcp_7c6e82dd/readme"
}