Qbconductor MCP Server

QuickBooks桌面MCP服务器

一个全面的模型上下文协议（MCP）服务器，通过Conductor API为Claude提供对QuickBooks桌面操作的直接访问。此服务器支持与QuickBooks的自然语言交互，用于财务管理、账单处理、付款处理和综合报告。

🚀 特性

核心能力

• 最终用户管理：创建和管理QuickBooks最终用户
• 身份验证流程：处理QuickBooks桌面身份验证会话
• 账户管理：会计科目表的完整CRUD操作
• 账单处理：使用行项目创建、更新和管理供应商账单
• 支付处理：处理支票和信用卡账单付款
• 财务报告：生成摘要并分析供应商支出模式
• 高级操作：直接API访问和批量操作

技术特性

• 多租户支持：与多家QuickBooks公司打交道
• 强健的缓存：本地缓存系统，用于优化缓慢的Conductor API调用
• 全面的错误处理：重试逻辑和详细的错误消息
• 输入验证：对所有操作进行基于Zod的模式验证
• 财务格式：正确的货币显示和金额处理
• 分页支持：大型数据集的基于光标的导航

📋 先决条件

• Node.js 18+和npm
• 集成Conductor的QuickBooks桌面
• 导体API证书（密钥、可发布密钥）

🛠️ 安装

选项1:克劳德桌面集成（推荐）

使用此服务器最简单的方法是通过Claude Desktop直接安装git：

1. 克隆并构建存储库

   git clone https://github.com/alfork/qbconductor-mcp-server.git
   cd qbconductor-mcp-server
   npm install
   npm run build

1. 添加到Claude桌面配置

打开您的Claude Desktop配置文件并添加：

   {
     "mcpServers": {
       "QuickBooks": {
         "command": "node",
         "args": ["/absolute/path/to/qbconductor-mcp-server/dist/index.js"],
         "env": {
           "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
           "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
           "CONDUCTOR_END_USER_ID": "end_usr_your_default_user",
           "CONDUCTOR_API_BASE_URL": "https://api.conductor.is/v1"
         }
       }
     }
   }

1. 重新启动克劳德桌面

服务器将从本地安装加载。

选项2：地方发展设置

对于本地开发或自定义部署：

1. 克隆存储库

   git clone https://github.com/alfork/qbconductor-mcp-server.git
   cd qbconductor-mcp-server

1. 安装依赖项

   npm install

1. 配置环境变量

   cp .env.example .env

编辑 .env 使用您的API指挥证书：

   CONDUCTOR_SECRET_KEY=your_secret_key_here
   CONDUCTOR_API_KEY=your_publishable_key_here
   CONDUCTOR_END_USER_ID=your_default_end_user_id
   CONDUCTOR_API_BASE_URL=https://api.conductor.is/v1
   LOG_LEVEL=info
   CACHE_TTL_MINUTES=30
   CACHE_MAX_SIZE=1000

1. 构建项目

   npm run build

🔧 配置

Claude桌面配置（推荐）

配置此服务器的首选方式是通过Claude Desktop的配置文件。这种方法提供了最佳的用户体验，并自动处理所有依赖关系。

所需配置

将以下内容添加到您的Claude桌面 claude_desktop_config.json:

{
  "mcpServers": {
    "QuickBooks": {
      "command": "node",
      "args": ["/absolute/path/to/qbconductor-mcp-server/dist/index.js"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
        "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
        "CONDUCTOR_END_USER_ID": "end_usr_your_default_user"
      }
    }
  }
}

可选配置

您可以通过添加以下可选环境变量来自定义服务器行为：

{
  "mcpServers": {
    "QuickBooks": {
      "command": "node",
      "args": ["/absolute/path/to/qbconductor-mcp-server/dist/index.js"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
        "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
        "CONDUCTOR_END_USER_ID": "end_usr_your_default_user",
        "CONDUCTOR_API_BASE_URL": "https://api.conductor.is/v1",
        "LOG_LEVEL": "info",
        "CACHE_TTL_MINUTES": "30",
        "CACHE_MAX_SIZE": "1000",
        "DISABLED_TOOLS": "passthrough_request,bulk_operations"
      }
    }
  }
}

配置参数

备选方案：环境变量

对于本地开发或自定义MCP客户端集成，您可以使用环境变量：

自定义MCP客户端配置

对于自定义MCP客户端，请使用以下配置：

{
  "mcpServers": {
    "qbconductor": {
      "command": "node",
      "args": ["/path/to/qbconductor-mcp-server/dist/index.js"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "your_secret_key",
        "CONDUCTOR_API_KEY": "your_publishable_key",
        "CONDUCTOR_END_USER_ID": "your_end_user_id"
      }
    }
  }
}

🎯 可用工具

最终用户管理

• create_end_user -创建新的QuickBooks最终用户
• list_end_users -列出所有最终用户
• get_end_user -检索特定的最终用户详细信息
• delete_end_user -删除最终用户

认证

• create_auth_session -生成QuickBooks身份验证URL
• check_connection_status -验证最终用户连接状态

账户管理

• list_accounts -通过过滤获取会计科目表
• get_account -检索帐户详细信息
• create_account -创建新的财务账户
• update_account -修改现有帐户

票据管理

• list_bills -通过全面过滤检索账单
• get_bill -检索特定账单详细信息
• create_bill -使用行项目创建新的供应商账单
• update_bill -修改现有账单

支付处理

• list_bill_check_payments -获取账单的支票付款
• list_bill_credit_card_payments -获取信用卡付款
• create_bill_check_payment -通过支票处理账单付款
• create_bill_credit_card_payment -处理信用卡账单付款
• update_payment -修改现有付款
• delete_payment -删除付款

报告和分析

• get_account_tax_lines -检索税行信息
• generate_financial_summary -跨账户汇总财务数据
• get_vendor_spending_analysis -按供应商分析支出

高级操作

• passthrough_request -API直接调用自定义操作
• bulk_operations -多笔交易的批处理

💡 使用示例

基本账户操作

Claude: "Show me all expense accounts in QuickBooks"
→ Uses: list_accounts with accountType filter

Claude: "Create a new expense account called 'Marketing Software'"
→ Uses: create_account with proper account details

票据管理

Claude: "Show me all unpaid bills from this month"
→ Uses: list_bills with date range and payment status filters

Claude: "Create a bill for $500 from Office Depot for office supplies"
→ Uses: create_bill with vendor and line item details

支付处理

Claude: "Pay the Office Depot bill via check from our main checking account"
→ Uses: create_bill_check_payment with account and bill references

Claude: "Show me all payments made to vendors this quarter"
→ Uses: list_bill_check_payments and list_bill_credit_card_payments

财务分析

Claude: "Generate a financial summary for all expense accounts"
→ Uses: generate_financial_summary with account type filtering

Claude: "Analyze our spending by vendor for the last 6 months"
→ Uses: get_vendor_spending_analysis with date range

🏗️ 建筑

项目结构

src/
├── config.ts                 # Configuration management
├── logger.ts                 # Logging setup
├── index.ts                  # Server entry point
├── server.ts                 # MCP server implementation
├── services/
│   ├── conductor-client.ts   # Conductor API client
│   └── cache-service.ts      # Local caching service
├── schemas/
│   ├── conductor-types.ts    # Conductor API type definitions
│   └── mcp-schemas.ts        # MCP input validation schemas
├── utils/
│   ├── validation.ts         # Input validation utilities
│   ├── formatting.ts         # Response formatting utilities
│   └── error-handling.ts     # Error handling utilities
└── tools/
    ├── index.ts              # Tool registry
    ├── end-users.ts          # End-user management tools
    ├── auth.ts               # Authentication tools
    ├── accounts.ts           # Account management tools
    ├── bills.ts              # Bill management tools
    ├── payments.ts           # Payment processing tools
    ├── reporting.ts          # Reporting and analysis tools
    └── advanced.ts           # Advanced operation tools

关键组件

指挥客户

• 与Conductor直接集成REST API
• 瞬态故障的自动重试逻辑
• 全面的错误处理和记录
• 内置缓存以优化性能

缓存服务

• 本地缓存以减少API调用
• 可配置的TTL和大小限制
• 基于模式的缓存失效
• 性能监控和统计

输入验证

• 所有工具的基于Zod的模式验证
• 类型安全参数处理
• 无效输入的全面错误消息

响应格式

• 所有工具的一致响应结构
• 带货币显示的财务金额格式
• 元数据包含（时间戳、ID、修订号）
• 包含摘要和分页信息的列表格式

🔒 安全

• API密钥管理：安全的环境变量处理
• 输入消毒：全面验证所有输入
• 错误处理：错误消息中没有敏感数据泄露
• 多租户隔离：适当的最终用户上下文管理

🧪 测试

运行测试套件：

npm test

构建并验证：

npm run build
npm run lint

📚 api参考

工具输入模式

所有工具都根据其定义的模式接受参数。常见参数包括：

• endUserId （可选）：覆盖多租户场景的默认最终用户
• 日期筛选器：使用 YYYY-MM-DD 日期范围的格式
• 分页：基于光标的大型结果集导航
• 过滤：支持各种QuickBooks过滤模式

响应格式

所有工具都以以下格式返回响应：

{
  "success": true,
  "data": { /* tool-specific data */ },
  "metadata": {
    "endUserId": "user_123",
    "timestamp": "2024-01-01T00:00:00Z",
    "totalCount": 10,
    /* additional metadata */
  }
}

错误响应：

{
  "success": false,
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "details": { /* additional error context */ }
  }
}

🚀 部署

地方发展

npm run dev

生产建设

npm run build
npm start

Docker部署

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["node", "dist/index.js"]

📦 向NPM发布

出版的先决条件

1. NPM账户：在以下网址创建帐户
2. NPM CLI：确保npm已安装并更新
3. 认证：从命令行登录到NPM

发布步骤

1. 登录NPM

   npm login
   # Enter your NPM username, password, and email

1. 验证包配置

   # Check package.json is properly configured
   npm run build
   npm test

1. 版本管理

   # For patch releases (bug fixes)
   npm version patch

   # For minor releases (new features)
   npm version minor

   # For major releases (breaking changes)
   npm version major

1. 发布到NPM

   # Publish to public registry
   npm publish --access public

   # For scoped packages (recommended)
   npm publish --access public

1. 验证发布

   # Check if package is available
   npm view @alfork/qbconductor-mcp-server

   # Test installation
   npx @alfork/qbconductor-mcp-server@latest --help

出版后

成功发布后，更新文档以使用NPM安装：

{
  "mcpServers": {
    "QuickBooks": {
      "command": "npx",
      "args": ["-y", "@alfork/qbconductor-mcp-server@latest"],
      "env": {
        "CONDUCTOR_SECRET_KEY": "sk_prod_your_secret_key",
        "CONDUCTOR_API_KEY": "pk_prod_your_publishable_key",
        "CONDUCTOR_END_USER_ID": "end_usr_your_default_user"
      }
    }
  }
}

📖 文档

• 安装指南 -详细的安装和配置说明
• 贡献指南 -贡献者指南
• api参考 -全面的API文件
• 例子 -使用示例和集成模式
• 故障排除 -常见问题和解决方案

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 提交您的更改： git commit -m 'Add amazing feature'
4. 推到分支： git push origin feature/amazing-feature
5. 打开拉取请求

看 贡献.md 详细指南。

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

有关支持和问题：

• 在此存储库中创建问题
• 查看 导线API文件
• 检查 MCP规范

🔗 相关项目

• 导线API文件
• 模型上下文协议
• 点击MCP服务器 （参考实施）