AI导哈

QuickBooks MCP服务器

一个用于QuickBooks Online集成的Model Context Protocol (MCP)服务器的原生Go实现，支持多种传输模式和平台集成。

  • by eakomdo
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 eakomdo/quickbooks-mcp-server

使用说明

QuickBooks在线MCP服务器

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

快速开始

先决条件

  • 转到1.25+
  • QuickBooks在线凭证

构建与运行

# Build the binary
go build -o qbo-mcp ./cmd/qbo-mcp

# Run with stdio (default for local MCP clients)
./qbo-mcp

# Or run with HTTP
PORT=3000 ./qbo-mcp

运输方式

  • 标准（默认） --适用于Claude Desktop和本地MCP客户端。不 PORT 需要环境变量。
  • HTTP（流式MCP） --设置 PORT （例如。， PORT=3000)或 MCP_TRANSPORT=httpHTTP路径默认为 /mcp （可定制 MCP_HTTP_PATH).

配置

在中设置环境变量 .env 文件或导出它们。在单租户模式下，如果未提供QuickBooks凭据，服务器将在启动时主动提示您缺少这些凭据：

# QuickBooks API credentials
QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_REALM_ID=your_realm_id
QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_ENVIRONMENT=sandbox  # or 'production'

# Optional: Platform integration (multi-tenant mode)
PLATFORM_INT_URL=https://platform-api.example.com
ENFORCE_AUTH=true

# Optional: Usage tracking
USAGE_REPORT_ENDPOINT=https://usage-tracker.example.com

# Optional: License server integration
LICENSE_SERVER_BASE_URL=https://license-server.example.com
LICENSE_SERVER_JWKS_ENDPOINT=/.well-known/jwks.json
LICENSE_SERVER_ACTIVATION_ENDPOINT=/activate
LICENSE_KEY=your_license_key

# Optional: HTTP server
PORT=3000
MCP_HTTP_PATH=/mcp

获取凭据

  1. 去 Intuit开发者门户
  2. 创建或选择您的应用程序
  3. 复制您的客户端ID和客户端密码
  4. 添加 http://localhost:3000/callback 到应用程序的重定向URI
  5. 获取您的刷新令牌和领域ID（请参阅下面的OAuth流程）

认证

选项1：预配置令牌（建议用于本地开发）

如果您已经拥有刷新令牌和领域ID：

QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id

选项2:OAuth流设置

服务器使用您的 QUICKBOOKS_REFRESH_TOKEN。要获得初始令牌，请执行以下操作：

  1. 在中使用Intuit OAuth流 开发者门户
  2. 保存返回的 refresh_token 和 realmId
  3. 将它们添加到您的 .env 文件

可用工具

服务器为QuickBooks Online实体提供以下工具操作：

支持的实体：

  • 账户
  • 比尔
  • 账单支付
  • 客户
  • 员工
  • 估计
  • 发票
  • 物品
  • 日记
  • 购买
  • 供应商

操作：

  • quickbook_create_* --创建新实体
  • quickbook_get_* --按ID检索实体
  • quickbook_update_* --更新现有实体
  • quickbook_delete_* --删除/停用实体
  • quickbook_search_* --使用条件搜索实体

例子： quickbook_search_customers, quickbook_create_invoice, quickbook_update_bill

平台集成模式

对于多租户部署，设置 PLATFORM_INT_URL 为了实现平台集成：

PLATFORM_INT_URL=https://platform-api.example.com
ENFORCE_AUTH=true

在此模式下：

  • 服务器使用请求的承载令牌从API平台获取QuickBooks凭据
  • 每个HTTP请求都必须包含一个有效的 Authorization: Bearer <token> 头球
  • Bearer令牌用于检索经过身份验证的用户的QB项目凭据

Docker部署

构建Docker镜像

docker build -t qbo-mcp-server:latest .

使用compose.yaml运行（HTTP模式）

docker compose up

这将在上运行服务器 http://localhost:3000/mcp

使用docker-compose.yaml运行（生产）

SHA=latest docker compose -f docker-compose.yaml up

这假设凭据位于 .env 并将端口8011映射到集装箱的端口3000。

错误处理

“QuickBooks未连接”

  • 验证 .env 包含所有必需的变量
  • 检查令牌是否有效（刷新令牌定期过期）
  • 对于平台模式，确保Bearer令牌有效并且可以访问QB凭据

“缺少授权令牌”

  • 在平台集成模式下，包括 Authorization: Bearer <token> 在HTTP请求中
  • 或禁用 ENFORCE_AUTH=false 促进地方发展

“OAuth令牌无效”

  • 您的刷新令牌可能已过期；通过OAuth流重新进行身份验证
  • 验证 QUICKBOOKS_ENVIRONMENT 匹配您的凭据颁发的位置

发展

项目结构

.
├── cmd/
│   └── qbo-mcp/
│       └── main.go           # Server entry point
├── internal/
│   ├── config/
│   │   └── config.go         # Configuration & environment loading
│   ├── qbo/
│   │   ├── client.go         # QB API client
│   │   ├── query.go          # Query building
│   │   ├── unwrap.go         # Response parsing
│   │   └── customer_delete.go # Entity-specific operations
│   └── tools/
│       ├── register.go       # Tool registration
│       └── helpers.go        # Utility functions
└── go.mod / go.sum         # Go module management

运行测试

go test ./...

构建标志

# Disable CGO for better portability
CGO_ENABLED=0 go build -o qbo-mcp ./cmd/qbo-mcp

# Linux binary for Docker
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o qbo-mcp ./cmd/qbo-mcp

许可证

麻省理工学院

支持

有关问题、疑问或贡献，请参阅 贡献.md 和 文件.md.

相关 MCP