QuickBooks Desktop MCP Server

Name: QuickBooks Desktop MCP Server
Author: alfork

本地服务

github.com/alfork生产力174 周前更新

代码仓库

关于 QuickBooks Desktop MCP Server

QuickBooks Desktop MCP Server 通过 Conductor API 将 Claude 等 MCP 客户端连接到 QuickBooks Desktop。它提供账户、账单、付款和财务分析工具，并支持多租户及可配置缓存。

主要功能

01管理 QuickBooks 终端用户和认证
02创建和更新账户与账单
03处理支票和信用卡付款
04生成财务与供应商报告
05批量操作和 API 直通调用

适用场景

01查看账户和供应商支出数据
02创建账单并记录账单付款
03管理多个 QuickBooks 公司

MCP 相关

该 MCP 服务通过 Conductor API 工具向 MCP 客户端提供 QuickBooks Desktop 操作，包括账户、账单、付款和报告功能。

#qbconductor #quickbooks #mcp-server

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "qbconductor": {
      "command": "npx",
      "args": [
        "-y",
        "@alfork/qbconductor-mcp-server"
      ]
    }
  }
}

启动命令npx -y @alfork/qbconductor-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@alfork/qbconductor-mcp-serverstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

QuickBooks Desktop MCP 服务

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

🚀 功能

核心能力

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

技术特性

多租户支持：处理多家 QuickBooks 公司
稳健的缓存：本地缓存系统，可优化缓慢的 Conductor API 调用
全面的错误处理：重试逻辑和详细的错误消息
输入验证：使用基于 Zod 的架构验证所有操作
财务格式化：正确显示货币并处理金额
分页支持：通过游标浏览大型数据集

📋 前提条件

Node.js 18+ 和 npm
已集成 Conductor 的 QuickBooks Desktop
Conductor API 凭据（密钥、可发布密钥）

🛠️ 安装

选项 1：集成 Claude Desktop（推荐）

使用此服务最简单的方式是通过 Claude Desktop 直接从 Git 安装：

克隆并构建代码库

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

添加到 Claude Desktop 配置

打开 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"
      }
    }
  }
}

重启 Claude Desktop

服务将从本地安装目录加载。

选项 2：本地开发环境设置

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

克隆代码库

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

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

配置环境变量

cp .env.example .env

编辑 .env，填入 Conductor 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 Desktop 配置（推荐）

建议通过 Claude Desktop 配置文件来配置此服务。此方式可提供最佳用户体验，并自动处理所有依赖项。

必需配置

将以下内容添加到 Claude Desktop 的 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`	Conductor API 密钥（以 `sk_` 开头）	是	-
`CONDUCTOR_API_KEY`	Conductor API 可发布密钥（以 `pk_` 开头）	是	-
`CONDUCTOR_END_USER_ID`	操作的默认最终用户 ID（以 `end_usr_` 开头）	是	-
`CONDUCTOR_API_BASE_URL`	Conductor API 基础 URL	否	`https://api.conductor.is/v1`
`LOG_LEVEL`	日志级别（debug、info、warn、error）	否	`info`
`CACHE_TTL_MINUTES`	缓存生存时间（分钟）	否	`30`
`CACHE_MAX_SIZE`	缓存项目的最大数量	否	`1000`
`DISABLED_TOOLS`	以逗号分隔的要禁用的工具列表	否	-

替代方案：环境变量

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

变量	描述	必填	默认值
`CONDUCTOR_SECRET_KEY`	Conductor API 密钥	是	-
`CONDUCTOR_API_KEY`	Conductor API 可公开密钥	是	-
`CONDUCTOR_END_USER_ID`	操作的默认最终用户 ID	否	-
`CONDUCTOR_API_BASE_URL`	Conductor API 基础 URL	否	`https://api.conductor.is/v1`
`LOG_LEVEL`	日志级别（debug、info、warn、error）	否	`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 客户端

与 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
创建 Pull Request

详细指南请参阅 CONTRIBUTING.md。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🆘 支持

如需支持或有任何问题：

在此仓库中创建 issue
查看 Conductor API 文档
查看 MCP 规范

🔗 相关项目

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

QuickBooks Desktop MCP Server

关于 QuickBooks Desktop MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

QuickBooks Desktop MCP 服务

🚀 功能

核心能力

技术特性

📋 前提条件

🛠️ 安装

选项 1：集成 Claude Desktop（推荐）

选项 2：本地开发环境设置

🔧 配置

Claude Desktop 配置（推荐）

必需配置

可选配置

配置参数

替代方案：环境变量

自定义 MCP 客户端配置

🎯 可用工具

最终用户管理

身份验证

账户管理

账单管理

付款处理

报告与分析

高级操作

💡 使用示例

基本账户操作

账单管理

付款处理

财务分析

🏗️ 架构

项目结构

核心组件

Conductor 客户端

缓存服务

输入验证

响应格式化

🔒 安全

🧪 测试

📚 API 参考

工具输入模式

响应格式

🚀 部署

本地开发

生产构建

Docker 部署

📦 发布到 NPM

发布前提条件

发布步骤

发布后

📖 文档

🤝 贡献

📄 许可证

🆘 支持

🔗 相关项目

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？