使用说明

QuickBooks在线MCP服务器（Ruby）

用于QuickBooks Online集成的模型上下文协议（MCP）服务器的Ruby实现。

概述

此MCP服务器提供与QuickBooks Online交互的工具，允许您通过模型上下文协议创建、读取、更新、删除和搜索各种QuickBooks实体。

特性

完成以下QuickBooks实体的CRUD操作：

客户 -创建、获取、更新、删除、搜索
发票 -创建、读取、更新、搜索
估计 -创建、获取、更新、删除、搜索
账单 -创建、获取、更新、删除、搜索
供应商 -创建、获取、更新、删除、搜索
员工 -创建、获取、更新、搜索
日记账分录 -创建、获取、更新、删除、搜索
账单支付 -创建、获取、更新、删除、搜索
采购 -创建、获取、更新、删除、搜索
账户 -创建、更新、搜索
物品 -创建、读取、更新、搜索

先决条件

Ruby 3.0或更高版本（使用Ruby 3.0+测试）
Bundler用于依赖关系管理
QuickBooks Online开发人员帐户
QuickBooks应用程序凭据（客户端ID和客户端密码）

安装

克隆此存储库或将文件复制到本地计算机
安装依赖项：

bundle install

创建一个 .env 文件基于 .env.example:

cp .env.example .env

在中配置您的QuickBooks凭据 .env 文件：

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox

QuickBooks设置

去 Intuit开发者门户
创建新应用程序或选择现有应用程序
从应用程序的密钥部分获取客户端ID和客户端密钥
添加 http://localhost:8000/callback 指向应用程序的重定向URI

认证

有两种方法可以通过QuickBooks Online进行身份验证：

选项1：使用环境变量

如果您已经有刷新令牌和领域ID，请将它们添加到您的 .env 文件：

QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id

选项2：使用OAuth流

如果您没有刷新令牌，服务器将在首次使用时自动启动OAuth流：

运行服务器
浏览器窗口将自动打开
登录QuickBooks并授权应用程序
代币将保存到您的 .env 文件自动
您可以关闭浏览器窗口

测试

在生产环境中使用服务器之前，请对其进行测试以确保一切正常：

快速测试

运行附带的测试脚本：

ruby test_server.rb

这将验证：

服务器正确启动
所有工具均已注册
基本MCP协议通信工作

综合测试

详细的测试说明包括：

使用MCP检查器（推荐）
手动stdio测试
Claude桌面集成
使用RSpec进行自动化测试

看 测试.md 获取完整的测试指南。

用法

作为Stdio服务器运行（适用于Claude Desktop）

使可执行文件可运行（仅限第一次）：

chmod +x bin/quickbooks_mcp_server

运行服务器：

./bin/quickbooks_mcp_server

或者直接使用Ruby：

ruby bin/quickbooks_mcp_server

作为HTTP服务器运行（用于Rails/Web应用程序）

使用HTTP传输运行服务器：

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

使用无状态模式（建议用于生产/扩展）：

PORT=3001 STATELESS=true ./bin/quickbooks_mcp_http

服务器将在以下时间可用 http://localhost:3001 并接受JSON-RPC 2.0请求。

可用工具

服务器公开了以下MCP工具：

客户运营

create_customer -创建新客户
get_customer -通过ID获取客户
update_customer -更新客户
delete_customer -删除（停用）客户
search_customers -使用筛选器搜索客户

发票操作

create_invoice -创建新发票
read_invoice -按ID读取发票
update_invoice -更新发票
search_invoices -使用筛选器搜索发票

估算运营

create_estimate -创建新的估算
get_estimate -按ID获取估计值
update_estimate -更新估算
delete_estimate -删除估算
search_estimates -使用过滤器搜索估计值

账单操作

create_bill -创建新账单
get_bill -按ID获取账单
update_bill -更新账单
delete_bill -删除账单
search_bills -使用过滤器搜索账单

供应商运营

create_vendor -创建新供应商
get_vendor -按ID获取供应商
update_vendor -更新供应商
delete_vendor -删除（停用）供应商
search_vendors -使用筛选器搜索供应商

员工运营

create_employee -创建新员工
get_employee -按ID获取员工
update_employee -更新员工
search_employees -使用筛选器搜索员工

日记账录入操作

create_journal_entry -创建新日记条目
get_journal_entry -按ID获取日记条目
update_journal_entry -更新日记条目
delete_journal_entry -删除日记条目
search_journal_entries -使用筛选器搜索日记条目

账单支付操作

create_bill_payment -创建新的账单付款
get_bill_payment -通过ID获取账单付款
update_bill_payment -更新账单付款
delete_bill_payment -删除账单付款
search_bill_payments -使用过滤器搜索账单付款

采购操作

create_purchase -创建新购买
get_purchase -按ID购买
update_purchase -更新购买
delete_purchase -删除购买
search_purchases -使用筛选器搜索购买

账户操作

create_account -创建新帐户
update_account -更新帐户
search_accounts -使用筛选器搜索帐户

项目操作

create_item -创建新项目
read_item -按ID读取项目
update_item -更新项目
search_items -使用筛选器搜索项目

搜索条件

所有搜索操作都支持灵活的过滤：

# Simple search
{
  criteria: [
    { field: "DisplayName", value: "John Doe", operator: "=" }
  ]
}

# Advanced search with pagination and sorting
{
  criteria: [
    { field: "Active", value: true, operator: "=" }
  ],
  limit: 10,
  offset: 0,
  asc: "DisplayName"
}

支持的操作员： =, <, >, <=, >=, LIKE, IN

Ruby API

服务器提供JSON-RPC接口（用于MCP客户端）和Ruby友好的API（用于Ruby代码中的直接使用）：

# Simple usage (uses ENV variables)
qb = QuickbooksMCPServer.new

# Multi-tenant usage (explicit credentials)
qb = QuickbooksMCPServer.new(
  client_id: organization.quickbooks_client_id,
  client_secret: organization.quickbooks_client_secret,
  refresh_token: organization.quickbooks_refresh_token,
  realm_id: organization.quickbooks_realm_id,
  environment: 'sandbox'
)

# Ruby-friendly methods
customers = qb.search_customers(limit: 50)
customer = qb.get_customer('123')
invoice = qb.create_invoice(invoice_data)

# Generic tool calling
result = qb.call_tool('search_vendors', { limit: 10 })

# List available tools
tools = qb.list_tools

看 API_REFERENCE.md 获取完整的方法文档。

在Rails应用程序中使用

将其作为本地gem包含在Rails应用程序中的最简单方法是：

# In your Rails app's Gemfile
gem 'quickbooks_mcp', path: '../ruby-quickbooks-mcp-server'

# Or from git
gem 'quickbooks_mcp', git: 'https://github.com/yourusername/ruby-quickbooks-mcp-server.git'

然后将其与Ruby-friendly API一起使用：

# app/controllers/customers_controller.rb
class CustomersController < ApplicationController
  def index
    qb = QuickbooksMCPServer.new(
      server_context: { user_id: current_user.id }
    )

    @customers = qb.search_customers(
      criteria: [{ field: 'Active', value: true, operator: '=' }],
      limit: 50
    )
  end

  def show
    qb = QuickbooksMCPServer.new
    @customer = qb.get_customer(params[:id])
  end
end

或者处理原始MCP JSON-RPC请求：

# app/controllers/quickbooks_mcp_controller.rb
class QuickbooksMcpController < ApplicationController
  def handle
    server = QuickbooksMCPServer.new(
      server_context: { user_id: current_user&.id }
    )
    render json: server.handle_request(request.body.read)
  end
end

看 轨道_设置.md 对于所有集成选项（本地gem、git gem、复制文件等）

Rails集成

想在Rails应用程序中使用此MCP服务器吗？看 RAILS_集成.md 用于：

直接Rails控制器集成
作为单独的HTTP服务运行
多租户支持
认证与安全
性能优化
完整的工作示例

Rails的快速示例：

# app/controllers/quickbooks_mcp_controller.rb
class QuickbooksMcpController < ApplicationController
  def handle
    server = QuickbooksMCPServer.new(
      server_context: { user_id: current_user&.id }
    )
    render json: server.handle_request(request.body.read)
  end
end

项目结构

ruby-quickbooks-mcp-server/
├── Gemfile                    # Ruby dependencies
├── README.md                  # This file
├── RAILS_INTEGRATION.md       # Rails integration guide
├── TESTING.md                 # Testing guide
├── .env.example              # Environment variables template
├── bin/
│   ├── quickbooks_mcp_server # Stdio server (for Claude Desktop)
│   └── quickbooks_mcp_http   # HTTP server (for Rails/web)
├── lib/
│   ├── quickbooks_mcp_server.rb  # Main server setup
│   ├── quickbooks_client.rb      # QuickBooks OAuth client
│   ├── helpers/
│   │   ├── format_error.rb       # Error formatting
│   │   └── search_criteria_builder.rb  # Query builder
│   └── tools/
│       ├── customer_tools.rb     # Customer CRUD tools
│       ├── invoice_tools.rb      # Invoice CRUD tools
│       ├── estimate_tools.rb     # Estimate CRUD tools
│       ├── bill_tools.rb         # Bill CRUD tools
│       ├── vendor_tools.rb       # Vendor CRUD tools
│       ├── employee_tools.rb     # Employee CRUD tools
│       ├── journal_entry_tools.rb # Journal Entry CRUD tools
│       ├── bill_payment_tools.rb  # Bill Payment CRUD tools
│       ├── purchase_tools.rb     # Purchase CRUD tools
│       ├── account_tools.rb      # Account CRUD tools
│       └── item_tools.rb         # Item CRUD tools
└── examples/
    ├── rails_controller_example.rb   # Rails controller example
    └── quickbooks_service_wrapper.rb # Service wrapper example

错误处理

所有工具都包括全面的错误处理，如果操作失败，将返回描述性错误消息。常见错误包括：

身份验证失败（令牌无效或过期）
缺少必填字段
实体ID无效
QuickBooks API错误

发展

此服务器使用：

mcp 用于MCP协议实现的gem（主分支）
quickbooks-ruby （~>2.0）用于QuickBooks API访问
oauth2 （~>1.4）用于OAuth 2.0身份验证
dotenv （~>3.1）用于环境变量管理
puma （~>6.5）用于OAuth回调服务器
rackup （~>2.2）用于机架应用支持

运输方式

此服务器支持两种传输模式：

标准传输（适用于克劳德桌面）

./bin/quickbooks_mcp_server

用于：Claude Desktop、MCP检查器、CLI工具

HTTP传输（用于Rails/Web应用程序）

PORT=3001 ./bin/quickbooks_mcp_http

用于：Rails应用程序、微服务、web API

看 部署.md 了解详细的部署选项和生产最佳实践。

与TypeScript版本的差异

此Ruby实现在遵循Ruby约定的同时，提供了与TypeScript版本相同的功能：

使用Ruby类和模块而不是TypeScript接口
用途 snake_case 用于方法和变量名
利用Ruby块进行工具定义
使用 quickbooks-ruby gem而不是 node-quickbooks
支持Stdio和StreamableHTTP传输
可以直接嵌入Rails应用程序中
保持相同的工具名称和功能以保持一致性

故障排除

“QuickBooks未通过身份验证”错误

确保你的 .env 文件包含有效的凭据和令牌。如果您正在使用OAuth流，请确保：

您的客户端ID和客户端密码正确
重定向URI与QuickBooks应用程序中配置的URI匹配
端口8000可用于OAuth回调服务器

令牌过期

刷新令牌在100天不活动后过期。如果您的令牌过期，只需删除 QUICKBOOKS_REFRESH_TOKEN 来自你的 .env 文件并再次运行服务器以重新进行身份验证。

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交pull请求或打开bug和功能请求的问题。