QuickBooks Online MCP Server

A Model Context Protocol (MCP) server for QuickBooks Online integration, enabling AI assistants like Claude to query and manage QuickBooks data through natural language.

Features

Customers: List, search, and view customer details
Invoices: Create and list invoices with filtering
Bills: Track vendor bills and payables
Vendors: Manage supplier information
Accounts: View chart of accounts
Reports: Generate Profit & Loss reports

Prerequisites

Node.js 18+
QuickBooks Online account
Intuit Developer account with OAuth app

Quick Start

1. Clone the repository

git clone https://github.com/hakeemrabiuDFW/quickbooks-mcp-server.git
cd quickbooks-mcp-server

2. Install dependencies

npm install

3. Configure environment

cp .env.example .env

Edit .env with your QuickBooks credentials:

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_COMPANY_ID=your_company_id
QUICKBOOKS_ENVIRONMENT=production

4. Build and run

npm run build
npm start

Getting QuickBooks Credentials

Step 1: Create Developer Account

Go to developer.intuit.com
Sign in or create account
Create a new app (select QuickBooks Online API)

Step 2: Get Client Credentials

In your app dashboard, find Client ID and Client Secret
Add OAuth redirect URI: http://localhost:3000/callback

Step 3: Get Refresh Token

Use the OAuth Playground in Intuit Developer portal
Or use a tool like qbo-oauth-tool
Complete OAuth flow to get refresh token

Step 4: Find Company ID (Realm ID)

Log into QuickBooks Online
Company ID is in the URL: https://qbo.intuit.com/app/...?realmId=COMPANY_ID

Claude Desktop Configuration

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp-server/dist/index.js"],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "your_client_id",
        "QUICKBOOKS_CLIENT_SECRET": "your_client_secret",
        "QUICKBOOKS_REFRESH_TOKEN": "your_refresh_token",
        "QUICKBOOKS_COMPANY_ID": "your_company_id",
        "QUICKBOOKS_ENVIRONMENT": "production"
      }
    }
  }
}

Available Tools

Tool	Description
`qbo_list_customers`	List customers with optional filtering
`qbo_list_invoices`	List invoices by customer, status, or date
`qbo_create_invoice`	Create a new invoice
`qbo_list_accounts`	View chart of accounts
`qbo_profit_loss_report`	Generate P&L report
`qbo_list_vendors`	List vendor/suppliers
`qbo_list_bills`	List bills/payables

Example Usage

Once connected to Claude:

"Show me all open invoices"
"Create an invoice for customer ID 123 with a $500 cleaning service charge"
"Get the profit and loss report for Q4 2025"
"List all unpaid bills"

HTTP Transport

To run as HTTP server instead of stdio:

TRANSPORT=http PORT=3000 npm start

Railway Deployment

Deploy to Railway with one click or via CLI:

Option 1: Railway Dashboard

Fork this repository
Go to Railway and create a new project
Select "Deploy from GitHub repo"
Add environment variables in Railway dashboard:
- QUICKBOOKS_CLIENT_ID
- QUICKBOOKS_CLIENT_SECRET
- QUICKBOOKS_REFRESH_TOKEN
- QUICKBOOKS_COMPANY_ID
- QUICKBOOKS_ENVIRONMENT=production
Railway will auto-deploy using the included Dockerfile

Option 2: Railway CLI

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

MCP Endpoint

Once deployed, your MCP endpoint will be:

https://your-app.railway.app/mcp

Health check available at:

https://your-app.railway.app/health

Docker Deployment (Local)

docker build -t quickbooks-mcp .
docker run -p 3000:3000 --env-file .env quickbooks-mcp

License

MIT

Author

Hakeem Rabiu - Martinez Cleaning LLC

Quickbooks-MCP-Martinez