Quickbooks Online

QuickBooks Online MCP Server

A comprehensive Model Context Protocol (MCP) server for QuickBooks Online

Quick Start | Available Tools | Authentication | Documentation

Overview

This MCP server provides complete QuickBooks Online API integration for Claude Code and other MCP-compatible clients. It includes full CRUD operations for 29 entity types and 11 financial reports, giving you comprehensive access to QuickBooks Online functionality.

Key Features

• 145 Total Tools - Complete coverage of QuickBooks Online API
• 29 Entity Types - Full CRUD operations (Create, Read, Update, Delete, Search)
• 11 Financial Reports - Balance Sheet, P&L, Cash Flow, and more
• OAuth 2.0 Authentication - Secure token-based authentication
• TypeScript - Full type safety with Zod validation
• Tested - Jest test suite with ESM support

Note: this is a local MCP server. It runs as a stdio subprocess on the developer's or partner's machine and authenticates to a QuickBooks Online company.

Before you start: This MCP server is easy to run once authenticated, but QuickBooks Online integration is gated by Intuit's OAuth app setup. You must register an app on the Intuit Developer Portal and complete a one-time, browser-based OAuth handshake. Sandbox supports http://localhost redirect URIs; production requires a public HTTPS callback for the initial authorization. After that initial handshake, the server runs locally without further browser interaction (until the 100-day refresh window lapses). See Authentication for full details.

Quick Start

Installation

# Clone the repository
git clone https://github.com/your-username/mcp-quickbooks-online.git
cd mcp-quickbooks-online

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Copy the template .env.example to .env in the root directory and fill in your values:

cp .env.example .env

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox
QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id

# Optional: restrict which tool categories are registered (default: all enabled)
# QUICKBOOKS_DISABLE_WRITE=true    # suppress create_* tools
# QUICKBOOKS_DISABLE_UPDATE=true   # suppress update_* tools
# QUICKBOOKS_DISABLE_DELETE=true   # suppress delete_* tools

.env is gitignored so your real credentials stay local.

Read-only or containerized installs: the server reads .env at startup and writes the rotated refresh token back to it on each refresh. When the installed module sits on a read-only filesystem (a container with a read-only root, an immutable/Nix install), set QUICKBOOKS_TOKEN_STORE_PATH to an absolute, writable path for both operations. A per-tenant host can also point each connection at its own isolated token file this way. Three things to know: it must be set in the host process env (e.g. the env block of your MCP server config) — setting it inside .env has no effect, because the path is resolved before .env is read; it must be an absolute path (the server refuses to start otherwise); and when set, the package's own .env is not read at all, so any file-based config (including credentials) must live in the file it points to.

Claude Code Integration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["path/to/mcp-quickbooks-online/dist/index.js"],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "your_client_id",
        "QUICKBOOKS_CLIENT_SECRET": "your_client_secret",
        "QUICKBOOKS_REFRESH_TOKEN": "your_refresh_token",
        "QUICKBOOKS_REALM_ID": "your_realm_id",
        "QUICKBOOKS_ENVIRONMENT": "sandbox",
        "QUICKBOOKS_DISABLE_WRITE": "false",
        "QUICKBOOKS_DISABLE_UPDATE": "false",
        "QUICKBOOKS_DISABLE_DELETE": "false"
      }
    }
  }
}

Set any of the DISABLE_* flags to "true" to prevent that category of tools from being registered. Read tools (get_*, search_*) are always available.

Available Tools

Entities

Complete CRUD operations are available for all entity types:

Reports

Tool Reference

Authentication

This server uses OAuth 2.0 to authenticate to a QuickBooks Online company. You'll set up an app on the Intuit Developer Portal and connect it to either a sandbox (for development) or your production QBO company.

Important: Sandbox vs Production

If you only want to read your own company's data, you still need to set up an app — Intuit does not offer per-user API keys. There is no shortcut around the OAuth + app-creation flow.

Sandbox Setup (recommended for first run)

1. Go to the Intuit Developer Portal and create a new app
2. Open the app → Settings (left sidebar) → Redirect URIs → add: http://localhost:8000/callback
3. Get your Client ID and Client Secret from the app's Keys & Credentials page (Development keys)
4. Create or use a sandbox company under the Sandbox top-level menu item in the dev portal
5. Set QUICKBOOKS_ENVIRONMENT=sandbox in your .env
6. Run npm run auth to complete the OAuth handshake — your browser will open, you sign in to the sandbox company, tokens are saved to .env

Production Setup

The Intuit Developer Portal rejects http://localhost redirect URIs in production mode — every contributor hits this. Two known workarounds:

1. ngrok tunnel (most common): run ngrok http 8000, then on your Intuit app go to Settings → Redirect URIs and add the generated https://<id>.ngrok-free.app/callback URL. Use that URL for the OAuth handshake, then revert to localhost afterwards.
2. Deploy a small public callback handler (e.g., on a VPS or serverless function) that captures the auth code and hands it back to your local setup. More involved; only needed if you can't use ngrok.

After completing the production OAuth handshake, the refresh token is what matters — once it's in .env, you no longer need the public redirect URL for day-to-day use. Refresh tokens auto-rotate; the server persists the new token on each refresh.

Once you have tokens

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id
QUICKBOOKS_ENVIRONMENT=sandbox  # or 'production'

Common pitfalls

• .env loaded from the wrong directory. The server resolves .env relative to the compiled module, not your shell's CWD. If you launch via Claude Desktop, this matters — make sure you're on current main.
• Redirect URI mismatch. The URI you register in the Intuit portal must match exactly — protocol, host, port, path. http://localhost:8000/callback .

Development

Building

npm run build

Testing

npm test

The test suite includes 396 tests with 100% code coverage across all metrics (statements, branches, functions, lines).

Project Structure

src/
├── clients/          # QuickBooks API client
├── handlers/         # Business logic handlers (87 files)
├── tools/           # MCP tool definitions
├── helpers/         # Utility functions
├── types/           # TypeScript types
└── index.ts         # Server entry point

tests/
├── unit/            # Unit tests (396 tests)
│   ├── handlers/    # Handler tests (15 test files)
│   └── helpers/     # Helper tests
└── mocks/           # Test mocks

docs/
├── ARCHITECTURE.md  # System architecture & design patterns
├── TESTING.md       # Testing guide & patterns
└── plans/           # Development plans

Documentation

Error Handling

If you encounter connection errors:

1. Verify all environment variables are set correctly
2. Check that tokens are valid and not expired
3. Ensure the QuickBooks app has the correct redirect URIs
4. For sandbox testing, use QUICKBOOKS_ENVIRONMENT=sandbox

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Tool naming convention

All tool names must follow the {verb}_{entity} convention using underscores. The verb prefix determines CRUD Restriction Mode behaviour:

New tools that do not follow this convention will not be correctly categorised and may appear or be suppressed unexpectedly.

License

MIT License - see LICENSE for details.

Acknowledgments

• Based on Intuit's QuickBooks Online MCP Server
• Built with the Model Context Protocol