QuickBooks MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个完整的 MCP 服务器，专为 QuickBooks Online 构建，提供对会计数据的资源管理、工具注册与执行，以及提示模板渲染能力，支持多种传输协议，便于在 AI 助手中使用上下文信息和外部功能。

• 主要功能点

  • MCP 协议核心：实现标准的 MCP 服务器框架，响应 MCP 客户端的请求、注册工具、执行工具、渲染提示等。
  • 资源与工具管理：托管并管理数据资源与 QuickBooks 相关工具，支持工具调用和结果返回。
  • 提示与模板：定义和渲染 Prompt 模板，帮助 LLM 客户端与服务器协作。
  • JSON-RPC 通信：通过 MCP 所使用的 JSON-RPC 风格请求/响应对客户端进行交互。
  • 会话与认证：内置会话管理、能力声明和可选的身份认证（支持基于 JWKS 的 Token 验证）。
  • 多传输协议：支持 STDIO 与基于 HTTP 的传输（包括 Lambda/API Gateway 场景）的服务器实现。
  • OAuth 与云配置：内置对 QuickBooks OAuth 流程的支持和代理，方便在不同部署环境下获取并刷新凭证。

• 安装步骤

  1. 确保环境满足 Node.js 18+ 的运行要求。
  2. 克隆仓库并进入项目目录，安装依赖。
  3. 根据需要选择部署方式：
     • 本地开发/检查：npm install；npm run build；npx quickbooks-mcp（或 node dist/index.js，按 dist 路径执行）。
     • 通过 Claude Code 等集成运行：参考 README 的选项，使用 npx quickbooks-mcp 即可自带 MCP 服务器。
     • 在 AWS/Azure 等云环境部署：按 README 配置环境变量与凭据管理，使用 Node.js 运行打包后的入口文件。
  4. 配置凭据与账户信息：
     • 本地模式：通过 qbo_authenticate 工具完成 OAuth 授权流程，凭据存储在本地（默认 ~/.quickbooks-mcp/credentials.json）。
     • AWS 模式：凭据存放在 AWS Secrets Manager，公司 ID 放在 SSM Parameter Store，需配置相应的 IAM 权限。
  5. 启动服务器后，按照 MCP 客户端的要求进行连接配置。

• 服务器配置（MCP 客户端需要提供此配置以连接服务器） 配置示例（仅描述，不提供代码块）： { "mcpServers": { "quickbooks": { "command": "npx", "args": ["-y", "quickbooks-mcp"] } // 说明： // - command: 启动 MCP 服务器的命令。若使用本地开发环境，常用为 npx quickbooks-mcp。 // - args: 传递给 command 的参数。README 还给出了本地开发和 AWS/Azure 部署下的替代方案。 // 客户端无需关注具体实现细节，只需提供启动命令与参数即可建立连接。 } }

• 基本使用方法

  • 启动后，MCP 客户端通过 JSON-RPC 调用服务器的工具列表、执行工具、获取提示等功能。
  • 客户端可以使用不同传输协议（如 STDIO 或 HTTP）来与 MCP 服务器交互，服务器侧实现会根据传输模式输出相应的结果。
  • 常用工具包括：
    • qbo_authenticate：本地凭据模式下的 OAuth 授权流程。
    • query、list_accounts、get_profit_loss 等工具，用于查询和报表。
    • create/get/edit 各类 QB 交易（发票、账单、支出、存款等）的创建与查询。
  • 如需调试或排错，可查看服务器日志与输出的报告文本（在 HTTP 模式下直接返回文本和数据；在 STDIO 模式下写入临时文件并返回路径）。

• 补充说明

  • 该实现包含对 OAuth 的代理、JWT 验证、Token 刷新等安全机制，支持本地和 AWS 模式两种凭据存储。
  • 代码覆盖资源、工具、提示、以及多种 QB 实体的创建/读取/更新/删除等全面功能，属于较为完整的 MCP 服务器实现。