quickbooks-online

This MCP server provides a QuickBooks Online integration through a Model Context Protocol (MCP) interface. It exposes tools to manage common QuickBooks entities such as customers, invoices, bills, items, and more, enabling Create, Read/Get, Update, Delete, and Search operations via the MCP tooling. After startup, you can authenticate using one of the supported methods (environment variables if you already have tokens, or the built-in OAuth flow) and then begin issuing MCP requests to manipulate QuickBooks data. The server handles token management and returns structured results suitable for integration into downstream MCP pipelines or chat/intelligence agents.

Once running, configure your MCP client to target the quickbooks-online server name. Use the available tools to perform typical operations like creating a new customer, retrieving an existing invoice, updating a bill, or searching for items. The tooling support spans the following entities: Account, Bill Payment, Bill, Customer, Employee, Estimate, Invoice, Item, Journal Entry, Purchase, and Vendor, with Create, Delete, Get, Search, and Update capabilities for each.

Prerequisites:

• Node.js and npm installed on your system
• Access to the repository containing this MCP server
• (Optional) QuickBooks Online app credentials for OAuth setup

Step 1: Install dependencies

npm install

Step 2: Prepare environment variables Create a .env file in the root directory with at least:

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox

If you already have tokens, you can also set:

QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id

Step 3: Start the MCP server

npm start

Note: If the project uses a different startup script, run the command documented in the repository (e.g., node server.js). Ensure your environment variables are loaded (e.g., via a .env loader like dotenv) when starting.

Step 4: OAuth setup (if needed)

• Go to the Intuit Developer Portal and create or select an app
• Add the Redirect URI (e.g., http://localhost:8000/callback)
• Use the built-in OAuth flow if you don’t yet have tokens; the server will guide you through authentication and persist tokens to .env when complete.

Tips and known considerations:

• Ensure QUICKBOOKS_ENVIRONMENT matches your intended QuickBooks Online environment (sandbox vs. production).
• When using the OAuth flow, the server may spin up a temporary local server and open a browser for authentication; tokens will be saved to your .env file.
• If you encounter a 'QuickBooks not connected' error, verify that all required environment variables are present and that the tokens have not expired; re-run the OAuth flow if necessary.
• Token and realm ID management: you can either provide tokens directly via environment variables or rely on the runtime OAuth flow to populate them.
• The server exposes multiple entities (Account, Bill Payment, Bill, Customer, Employee, Estimate, Invoice, Item, Journal Entry, Purchase, Vendor). Use the MCP tooling to perform CRUD operations and searches as needed for integration workflows.