使用说明

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：

克隆并构建存储库

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

添加到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"
      }
    }
  }
}

重新启动克劳德桌面

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

选项2：地方发展设置

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

克隆存储库

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

安装依赖项
```
npm install
```

配置环境变量

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

构建项目
```
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"
      }
    }
  }
}

配置参数

参数	说明	必填	默认
`CONDUCTOR_SECRET_KEY`	导体API密钥（以 `sk_`)	是	-
`CONDUCTOR_API_KEY`	导体API可发布密钥（以开头 `pk_`)	是	-
`CONDUCTOR_END_USER_ID`	操作的默认最终用户ID（以开头 `end_usr_`)	是	-
`CONDUCTOR_API_BASE_URL`	导线API基础URL	否	`https://api.conductor.is/v1`
`LOG_LEVEL`	日志记录级别（调试、信息、警告、错误）	否	`info`
`CACHE_TTL_MINUTES`	缓存生存时间（分钟）	否	`30`
`CACHE_MAX_SIZE`	缓存项目的最大数量	否	`1000`
`DISABLED_TOOLS`	以逗号分隔的禁用工具列表	否	-

备选方案：环境变量

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

变量	描述	必填	默认
`CONDUCTOR_SECRET_KEY`	指挥API密钥	是	-
`CONDUCTOR_API_KEY`	导体API可发布密钥	是	-
`CONDUCTOR_END_USER_ID`	操作的默认最终用户ID	否	-
`CONDUCTOR_API_BASE_URL`	导线API基础URL	否	`https://api.conductor.is/v1`
`LOG_LEVEL`	日志记录级别（调试、信息、警告、错误）	否	`info`
`CACHE_TTL_MINUTES`	缓存生存时间（分钟）	否	`30`
`CACHE_MAX_SIZE`	缓存项目的最大数量	否	`1000`

自定义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发布

出版的先决条件

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

发布步骤

登录NPM

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

验证包配置

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

版本管理

# For patch releases (bug fixes)
npm version patch

# For minor releases (new features)
npm version minor

# For major releases (breaking changes)
npm version major

发布到NPM

# Publish to public registry
npm publish --access public

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

验证发布

# 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文件
例子 -使用示例和集成模式
故障排除 -常见问题和解决方案

🤝 贡献

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

看贡献.md 详细指南。

📄 许可证

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

🆘 支持

有关支持和问题：

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

使用说明

QuickBooks桌面MCP服务器

🚀 特性

核心能力

技术特性

📋 先决条件

🛠️ 安装

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

选项2：地方发展设置

🔧 配置

Claude桌面配置（推荐）

所需配置

可选配置

配置参数

备选方案：环境变量

自定义MCP客户端配置

🎯 可用工具

最终用户管理

认证

账户管理

票据管理

支付处理

报告和分析

高级操作

💡 使用示例

基本账户操作

票据管理

支付处理

财务分析

🏗️ 建筑

项目结构

关键组件

指挥客户

缓存服务

输入验证

响应格式

🔒 安全

🧪 测试

📚 api参考

工具输入模式

响应格式

🚀 部署

地方发展

生产建设

Docker部署

📦 向NPM发布

出版的先决条件

发布步骤

出版后

📖 文档

🤝 贡献

📄 许可证

🆘 支持

🔗 相关项目

相关 MCP

Square MCP服务

支付协议服务器

AI支付管理服务器

餐厅POS管理插件

Lexware Office 财务管理MCP服务器

银行API交互工具