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_IDQUICKBOOKS_CLIENT_SECRETQUICKBOOKS_REFRESH_TOKENQUICKBOOKS_COMPANY_IDQUICKBOOKS_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