QuickBooks MCP Server

An MCP server for QuickBooks Online — built for bookkeepers, CFOs, and accountants who use AI assistants in their daily workflow.

Ask your AI assistant to pull a P&L report, create a journal entry, or investigate an account balance — using plain language, not API payloads.

Why This Server?

Intuit provides an official 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.

Use natural language, not internal IDs

Intuit'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:

"Create a bill for PG&E, $450 to Utilities, dated 2025-01-15"
→ Vendor, account, and department names are resolved automatically

Financial reports built in

This 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.

Safe by default

Every 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.

One query tool instead of dozens

Instead 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.

"SELECT * FROM Purchase WHERE TxnDate >= '2025-01-01' AND TxnDate <= '2025-01-31'"

Production-ready credential management

Store credentials locally for personal use, or in AWS Secrets Manager for shared environments. OAuth tokens refresh automatically and persist across sessions.

At a glance

	Intuit Official	This Server
Audience	Developers exploring the API	Bookkeepers, CFOs, accountants
Name resolution	Requires internal QB IDs	Resolves names automatically
Financial reports	None	P&L, Balance Sheet, Trial Balance
Write safety	Executes immediately	Draft preview by default
Query approach	Entity-specific search tools	SQL-like queries across all entities
Credentials	Local `.env` file	Local file or AWS Secrets Manager
Distribution	Clone from GitHub	`npx quickbooks-mcp`

Prerequisites

QuickBooks Developer Account: Register at developer.intuit.com
Node.js 18+

Installation Options

Choose the setup that fits your use case:

Setup	Best For
NPM Install	Quick setup, using your own QuickBooks app
Local Checkout	Development, customization
AWS Mode	Shared/production environments

Option 1: NPM Install

The simplest way to get started. Credentials are stored locally on your machine.

1. Create a QuickBooks App

Go to developer.intuit.com and sign in
Create a new app (or select an existing one)
Go to "Keys & credentials"
Note your Client ID and Client Secret
Under "Redirect URIs", add: https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl

2. Add to Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"]
    }
  }
}

3. Configure Credentials

Create ~/.quickbooks-mcp/credentials.json:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

4. Authenticate

Once Claude Code is running, use the qbo_authenticate tool:

Call qbo_authenticate with no arguments to get an authorization URL
Open the URL in your browser and authorize the app
Copy the code and realmId from the redirect URL
Call qbo_authenticate again with the authorization code and realm ID

Your OAuth tokens will be saved and automatically refreshed.

Option 2: Local Checkout

For development or customization.

1. Create a QuickBooks App

Follow the same steps as Option 1 above.

2. Clone and Build

git clone https://github.com/laf-rge/quickbooks-mcp.git
cd quickbooks-mcp
npm install
npm run build

3. Add to Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp/dist/index.js"]
    }
  }
}

4. Configure Credentials

Create ~/.quickbooks-mcp/credentials.json with your client credentials (same as Option 1), then run qbo_authenticate to complete the OAuth flow.

Option 3: AWS Mode

For shared or production environments. Stores credentials in AWS Secrets Manager.

1. Create AWS Resources

Create the secret in Secrets Manager:

aws secretsmanager create-secret \
  --name prod/qbo \
  --secret-string '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token",
    "redirect_url": "https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl"
  }'

Store Company ID in SSM Parameter Store:

aws ssm put-parameter \
  --name /prod/qbo/company_id \
  --value "your_company_id" \
  --type SecureString

2. Configure the Server

Create a .env file in the quickbooks-mcp directory:

QBO_CREDENTIAL_MODE=aws
AWS_REGION=us-east-2
QBO_SECRET_NAME=prod/qbo
QBO_COMPANY_ID_PARAM=/prod/qbo/company_id

Note: Due to a known Claude Code bug, environment variables from .mcp.json are not reliably passed to MCP servers. The .env file workaround is required.

3. Add to Claude Code

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp/dist/index.js"]
    }
  }
}

4. IAM Permissions

The server needs these AWS permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:prod/qbo*"
    },
    {
      "Effect": "Allow",
      "Action": ["ssm:GetParameter"],
      "Resource": "arn:aws:ssm:*:*:parameter/prod/qbo/*"
    }
  ]
}

Multi-Company Setup

If you have one QuickBooks account with multiple companies, you can connect them all by running a separate MCP server instance per company. Each instance uses the same Intuit developer app (same Client ID and Secret) but has its own credential file storing that company's OAuth tokens and Realm ID.

Note: This section covers multiple companies under a single QuickBooks account (one login, multiple company files). If you have separate QuickBooks accounts (different logins), each account requires its own Intuit developer app with its own Client ID and Secret.

1. Create one credential file per company

Each company gets its own credential file. The files only need your Client ID and Client Secret to start; the OAuth tokens and Realm ID are added when you authenticate.

mkdir -p ~/.quickbooks-mcp

# Create a starter credential file for each company
for company in acme widgets holdco; do
  echo '{ "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" }' \
    > ~/.quickbooks-mcp/${company}.json
  chmod 600 ~/.quickbooks-mcp/${company}.json
done

2. Add one MCP server entry per company

In your .mcp.json, create a separate entry for each company. They all point to the same server binary but use different credential files via QBO_CREDENTIAL_FILE:

{
  "mcpServers": {
    "quickbooks-acme": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"],
      "env": {
        "QBO_CLIENT_ID": "ABxx...your_client_id",
        "QBO_CLIENT_SECRET": "RRxx...your_client_secret",
        "QBO_CREDENTIAL_FILE": "/Users/you/.quickbooks-mcp/acme.json",
        "QBO_INLINE_OUTPUT": "true",
        "QBO_SANDBOX": "false"
      }
    },
    "quickbooks-widgets": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"],
      "env": {
        "QBO_CLIENT_ID": "ABxx...your_client_id",
        "QBO_CLIENT_SECRET": "RRxx...your_client_secret",
        "QBO_CREDENTIAL_FILE": "/Users/you/.quickbooks-mcp/widgets.json",
        "QBO_INLINE_OUTPUT": "true",
        "QBO_SANDBOX": "false"
      }
    },
    "quickbooks-holdco": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"],
      "env": {
        "QBO_CLIENT_ID": "ABxx...your_client_id",
        "QBO_CLIENT_SECRET": "RRxx...your_client_secret",
        "QBO_CREDENTIAL_FILE": "/Users/you/.quickbooks-mcp/holdco.json",
        "QBO_INLINE_OUTPUT": "true",
        "QBO_SANDBOX": "false"
      }
    }
  }
}

3. Authenticate each company

After restarting your AI assistant, authenticate each company one at a time. The OAuth flow will ask you to select which company to authorize:

Call qbo_authenticate on the quickbooks-acme server (no arguments) to get an authorization URL
Open the URL, sign in, and select the Acme company when prompted
Copy the code and realmId from the redirect URL
Call qbo_authenticate again with the code and realmId to complete the flow
Repeat for each company

Each company's OAuth tokens and Realm ID are saved to its own credential file. Tokens refresh automatically and independently.

How it works

Each MCP server instance is completely independent. Your AI assistant sees them as separate tool namespaces (e.g., quickbooks-acme__query vs quickbooks-widgets__query), so you can query across all companies in parallel or work with one at a time.

Inline Output Mode

By 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.

Set QBO_INLINE_OUTPUT=true to return all responses inline instead.

Option A — via .env file (recommended for local checkout):

Create a .env file in the quickbooks-mcp directory:

QBO_INLINE_OUTPUT=true

Option B — via .mcp.json env block (recommended for NPM install):

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"],
      "env": {
        "QBO_CREDENTIAL_MODE": "local",
        "QBO_CREDENTIAL_FILE": "~/.quickbooks-mcp/credentials.json",
        "QBO_INLINE_OUTPUT": "true"
      }
    }
  }
}

Note: Due to a known Claude Code bug, 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.

Environment Variables

Variable	Default	Description
`QBO_CREDENTIAL_MODE`	`local`	Credential storage: `local` or `aws`
`QBO_CLIENT_ID`	-	QuickBooks app Client ID (local mode)
`QBO_CLIENT_SECRET`	-	QuickBooks app Client Secret (local mode)
`QBO_CREDENTIAL_FILE`	`~/.quickbooks-mcp/credentials.json`	Custom credential file path
`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.
`QBO_SANDBOX`	`false`	Use QuickBooks sandbox environment
`AWS_REGION`	`us-east-2`	AWS region (aws mode)
`QBO_SECRET_NAME`	`prod/qbo`	Secrets Manager secret name (aws mode)
`QBO_COMPANY_ID_PARAM`	`/prod/qbo/company_id`	SSM parameter path (aws mode)

Available Tools

Tool	Description
Setup
`qbo_authenticate`	Set up OAuth credentials (local mode only)
`get_company_info`	Get connected company information
Query & Reports
`query`	Run SQL-like queries against any QuickBooks entity
`list_accounts`	List chart of accounts with filtering
`create_account`	Create a new account (top-level or sub-account) in the chart of accounts
`edit_account`	Rename, deactivate, re-parent, or edit description/number of an existing account
`get_profit_loss`	Profit & Loss report (by month, department, class, etc.)
`get_balance_sheet`	Balance Sheet report
`get_trial_balance`	Trial Balance report
`query_account_transactions`	All transactions affecting a specific account
`account_period_summary`	Period summary for an account (opening/closing balance, debits, credits, count)
Journal Entries
`create_journal_entry`	Create a journal entry (validates debits = credits)
`get_journal_entry`	Fetch a journal entry by ID
`edit_journal_entry`	Modify an existing journal entry
Bills
`create_bill`	Create a vendor bill
`get_bill`	Fetch a bill by ID
`edit_bill`	Modify an existing bill
Expenses
`create_expense`	Create an expense (Cash, Check, or Credit Card)
`get_expense`	Fetch an expense by ID
`edit_expense`	Modify an existing expense
`bulk_edit_expense`	Apply edit_expense to a batch of purchases in one call with per-item status
Sales Receipts
`create_sales_receipt`	Create a sales receipt with item lines
`get_sales_receipt`	Fetch a sales receipt by ID
`edit_sales_receipt`	Modify an existing sales receipt
Invoices
`create_invoice`	Create an invoice with item lines (customer required)
`get_invoice`	Fetch an invoice by ID
`edit_invoice`	Modify an existing invoice
Deposits
`create_deposit`	Create a bank deposit
`get_deposit`	Fetch a deposit by ID
`edit_deposit`	Modify an existing deposit
Vendor Credits
`create_vendor_credit`	Create a vendor credit
`get_vendor_credit`	Fetch a vendor credit by ID
`edit_vendor_credit`	Modify an existing vendor credit
Customers
`create_customer`	Create a customer or sub-customer
`get_customer`	Fetch a customer by ID
`edit_customer`	Modify an existing customer (set active=false to deactivate)
Vendors
`create_vendor`	Create a vendor with contact info, 1099 status, and payment terms
`get_vendor`	Fetch a vendor by ID (tax ID returned masked)
`edit_vendor`	Modify an existing vendor (set active=false to deactivate)
Bill Payments
`create_bill_payment`	Record a bill payment (Check or CreditCard) linked to vendor bills
`get_bill_payment`	Fetch a bill payment by ID
`edit_bill_payment`	Modify an existing bill payment
Employees
`get_employee`	Fetch an employee by ID
`edit_employee`	Modify an existing employee (set active=false to deactivate)
Delete
`delete_entity`	Delete any transaction (journal entry, bill, invoice, deposit, sales receipt, expense, vendor credit, bill payment)
Attachments
`create_attachment`	Upload a file from disk and link it to an existing QBO entity (Bill, Invoice, Purchase/Expense, JournalEntry, etc.)

Token Refresh

The server automatically refreshes OAuth tokens on each request and persists them back to your credential store (local file or AWS Secrets Manager).

Development

npm run dev      # Run in development mode
npm run build    # Build
npm run typecheck # Type check

Troubleshooting

"QuickBooks credentials not configured"

Run the qbo_authenticate tool to set up OAuth credentials (local mode only).

"Authorization code expired"

Authorization codes are only valid for a few minutes. Start the OAuth flow again.

Token refresh fails

Check that your refresh token hasn't expired (~100 days)
Verify your client credentials are correct
Try re-authenticating with qbo_authenticate

AWS credential errors

Ensure .env file has QBO_CREDENTIAL_MODE=aws
Check your AWS credentials and permissions
Verify the secret and parameter names match your configuration

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.claude/commands		.claude/commands
docs		docs
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

QuickBooks MCP Server

Why This Server?

Use natural language, not internal IDs

Financial reports built in

Safe by default

One query tool instead of dozens

Production-ready credential management

At a glance

Prerequisites

Installation Options

Option 1: NPM Install

1. Create a QuickBooks App

2. Add to Claude Code

3. Configure Credentials

4. Authenticate

Option 2: Local Checkout

1. Create a QuickBooks App

2. Clone and Build

3. Add to Claude Code

4. Configure Credentials

Option 3: AWS Mode

1. Create AWS Resources

2. Configure the Server

3. Add to Claude Code

4. IAM Permissions

Multi-Company Setup

1. Create one credential file per company

2. Add one MCP server entry per company

3. Authenticate each company

How it works

Inline Output Mode

Environment Variables

Available Tools

Token Refresh

Development

Troubleshooting

"QuickBooks credentials not configured"

"Authorization code expired"

Token refresh fails

AWS credential errors

About

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages