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

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

Step 2: Get Client Credentials

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

Step 3: Get Refresh Token

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

Step 4: Find Company ID (Realm ID)

1. Log into QuickBooks Online
2. 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

1. Fork this repository
2. Go to Railway and create a new project
3. Select "Deploy from GitHub repo"
4. Add environment variables in Railway dashboard:
   • QUICKBOOKS_CLIENT_ID
   • QUICKBOOKS_CLIENT_SECRET
   • QUICKBOOKS_REFRESH_TOKEN
   • QUICKBOOKS_COMPANY_ID
   • QUICKBOOKS_ENVIRONMENT=production
5. 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

Links

• QuickBooks API Docs
• MCP Protocol
• Tanda MCP Server