QuickBooks Online MCP Server (Ruby)

A Ruby implementation of the Model Context Protocol (MCP) server for QuickBooks Online integration.

Overview

This MCP server provides tools for interacting with QuickBooks Online, allowing you to create, read, update, delete, and search various QuickBooks entities through the Model Context Protocol.

Features

Complete CRUD operations for the following QuickBooks entities:

• Customers - Create, Get, Update, Delete, Search
• Invoices - Create, Read, Update, Search
• Estimates - Create, Get, Update, Delete, Search
• Bills - Create, Get, Update, Delete, Search
• Vendors - Create, Get, Update, Delete, Search
• Employees - Create, Get, Update, Search
• Journal Entries - Create, Get, Update, Delete, Search
• Bill Payments - Create, Get, Update, Delete, Search
• Purchases - Create, Get, Update, Delete, Search
• Accounts - Create, Update, Search
• Items - Create, Read, Update, Search

Prerequisites

• Ruby 3.0 or higher (tested with Ruby 3.0+)
• Bundler for dependency management
• A QuickBooks Online developer account
• QuickBooks app credentials (Client ID and Client Secret)

Installation

1. Clone this repository or copy the files to your local machine

2. Install dependencies:

bundle install

3. Create a .env file based on .env.example:

cp .env.example .env

4. Configure your QuickBooks credentials in the .env file:

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox

QuickBooks Setup

1. Go to the Intuit Developer Portal
2. Create a new app or select an existing one
3. Get the Client ID and Client Secret from the app's keys section
4. Add http://localhost:8000/callback to the app's Redirect URIs

Authentication

There are two ways to authenticate with QuickBooks Online:

Option 1: Using Environment Variables

If you already have a refresh token and realm ID, add them to your .env file:

QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id

Option 2: Using the OAuth Flow

If you don't have a refresh token, the server will automatically start an OAuth flow on first use:

1. Run the server
2. A browser window will open automatically
3. Sign in to QuickBooks and authorize the app
4. The tokens will be saved to your .env file automatically
5. You can close the browser window

Testing

Before using the server in production, test it to make sure everything works:

Quick Test

Run the included test script:

ruby test_server.rb

This will verify:

• Server starts correctly
• All tools are registered
• Basic MCP protocol communication works

Comprehensive Testing

For detailed testing instructions including:

• Using MCP Inspector (recommended)
• Manual stdio testing
• Claude Desktop integration
• Automated testing with RSpec

See TESTING.md for complete testing guide.

Usage

Running as Stdio Server (for Claude Desktop)

Make the executable file runnable (first time only):

chmod +x bin/quickbooks_mcp_server

Run the server:

./bin/quickbooks_mcp_server

Or using Ruby directly:

ruby bin/quickbooks_mcp_server

Running as HTTP Server (for Rails/Web Apps)

Run the server with HTTP transport:

chmod +x bin/quickbooks_mcp_http
PORT=3001 ./bin/quickbooks_mcp_http

With stateless mode (recommended for production/scaling):

PORT=3001 STATELESS=true ./bin/quickbooks_mcp_http

The server will be available at http://localhost:3001 and accepts JSON-RPC 2.0 requests.

Available Tools

The server exposes the following MCP tools:

Customer Operations

• create_customer - Create a new customer
• get_customer - Get customer by ID
• update_customer - Update a customer
• delete_customer - Delete (deactivate) a customer
• search_customers - Search custome

... View full README on GitHub