Ruby Quickbooks MCP Server

QuickBooks在线MCP服务器（Ruby）

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

概述

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

特性

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

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

先决条件

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

安装

1. 克隆此存储库或将文件复制到本地计算机

1. 安装依赖项：

bundle install

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

cp .env.example .env

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

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox

QuickBooks设置

1. 去 Intuit开发者门户
2. 创建新应用程序或选择现有应用程序
3. 从应用程序的密钥部分获取客户端ID和客户端密钥
4. 添加 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流：

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

测试

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

快速测试

运行附带的测试脚本：

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 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](DEPLOYMENT.md)** 了解详细的部署选项和生产最佳实践。

## 与TypeScript版本的差异

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

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

## 故障排除

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

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

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

### 令牌过期

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

## 许可证

麻省理工学院

## 贡献

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