QuickBooks Time MCP Server (Combined)

QuickBooks Time MCP 服务（V2 更新）

这是一个组合型 MCP 服务，可通过单一接口访问 QuickBooks Time API 的所有功能。它整合了以下四个独立服务的功能：

1. JobCode 工具
2. 报告与核心工具
3. 工时表工具
4. 用户工具

我非常希望能为改进这个项目出一份力！很高兴终于能回馈大家！

整个项目的开发和发布都借助了人工智能（Anthropic、OpenAI、Llama/META），因为我个人在没有协助的情况下无法编写多少代码。我们已尽力确保项目的质量和功能正常，但仍可能存在不足或有待改进之处。欢迎社区提供任何反馈、修正或建议。

1. 安装依赖项：

pip install -r requirements.txt

2. 创建 .env 文件，并填入你的 QuickBooks Time 访问令牌：

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude Desktop 配置

若要在 Claude Desktop 中使用此服务，需要在 Claude Desktop 设置中进行配置。以下是配置示例：

{
  "globalShortcut": "Ctrl+Q",
  "mcpServers": {
    "qb-time-tools": {
      "command": "python",
      "args": [
        "./qb-time-mcp-server/main.py"
      ],
      "env": {
        "QB_TIME_ACCESS_TOKEN": "your_quickbooks_time_access_token_here"
      }
    }
  }
}

可用工具

JobCode 工具

• get_jobcodes：获取 JobCode，并使用高级筛选选项

  • 基本筛选条件：
    • ids：（数字数组，可选）以逗号分隔的 JobCode ID 列表
    • name：（字符串，可选）按 JobCode 名称筛选，支持从字符串开头进行通配符（*）匹配
    • active：（字符串，可选）按状态筛选："yes"、"no"、"both"（默认值："yes"）
  • 类型和层级筛选条件：
    • type：（字符串，可选）按类型筛选："regular"、"pto"、"paid_break"、"unpaid_break"、"all"（默认值："regular"）
    • parent_ids：（数字数组，可选）按父级 JobCode ID 筛选。特殊值：0（仅顶层）、-1（所有层级）
  • 其他筛选条件：
    • customfields：（布尔值，可选）在响应中包含自定义字段
    • modified_before：（字符串，可选）按修改日期筛选（ISO 8601 格式）
    • modified_since：（字符串，可选）按修改日期筛选（ISO 8601 格式）
    • page：（数字）分页页码
    • limit：（数字）每页结果数（最多 200）

• get_jobcode：按 ID 获取指定 JobCode

  • 必需参数：
    • id：（数字）要获取的 JobCode 的 ID

• get_jobcode_hierarchy：获取完整的 JobCode 层级结构

  • 参数：
    • parent_ids：（数字数组，可选）按父级 ID 筛选。值：0（顶层）、-1（全部）或指定 ID
    • active：（字符串，可选）按状态筛选："yes"、"no"、"both"（默认值："yes"）
    • type：（字符串，可选）按类型筛选："regular"、"pto"、"paid_break"、"unpaid_break"、"all"（默认值："regular"）
    • customfields：（布尔值，可选）在响应中包含自定义字段

工时表工具

• get_timesheets：获取工时表并进行筛选

  • 必需参数（至少一个）：
    • ids：（数字数组）以逗号分隔的工时表 ID 列表
    • start_date：（字符串）返回此日期及之后的工时表（YYYY-MM-DD）
    • modified_before：（字符串）返回此时间之前修改的工时表（ISO 8601）
    • modified_since：（字符串）返回此时间起修改的工时表（ISO 8601）
  • 可选参数：
    • end_date：（字符串）返回此日期及之前的工时表（YYYY-MM-DD）
    • user_ids：（数字数组）按特定用户 ID 筛选
    • group_ids：（数字数组）按特定群组 ID 筛选
    • jobcode_ids：（数字数组）按特定工作代码 ID 筛选（包括子项）
    • payroll_ids：（数字数组）按特定工资单 ID 筛选
    • on_the_clock：（字符串）按当前工作状态筛选："yes"、"no"、"both"（默认值："no"）
    • jobcode_type：（字符串）按类型筛选："regular"、"pto"、"paid_break"、"unpaid_break"、"all"（默认值："all"）
    • page：（数字）页码
    • limit：（数字）每页结果数

• get_timesheet：按 ID 获取指定工时表

  • 必需参数：
    • id：（数字）要获取的工时表 ID

• get_current_timesheets：获取当前活跃的工时表

  • 必需参数：
    • on_the_clock：（字符串）必须设为 "yes"
  • 可选参数：
    • user_ids：（数字数组）筛选特定用户的活跃工时表
    • group_ids：（数字数组）筛选特定群组用户的活跃工时表
    • jobcode_ids：（数字数组）筛选特定工作代码的活跃工时表
    • supplemental_data：（字符串）是否包含补充数据："yes"、"no"（默认值："yes"）

用户工具

• get_users：获取所有用户并进行筛选

  • 用户标识筛选条件：
    • ids：（数字数组，可选）按特定用户 ID 筛选
    • not_ids：（数字数组，可选）排除特定用户 ID
    • employee_numbers：（数字数组，可选）按员工编号筛选
    • usernames：（字符串数组，可选）按特定用户名筛选
  • 群组筛选条件：
    • group_ids：（数字数组，可选）按群组成员身份筛选
    • not_group_ids：（数字数组，可选）排除特定群组中的用户
  • 状态和标识筛选条件：
    • payroll_ids：（字符串数组，可选）按工资标识号码筛选
    • active：（字符串，可选）按状态筛选："yes"、"no"、"both"（默认值："yes"）
  • 姓名筛选条件：
    • first_name：（字符串，可选）按名字筛选（支持通配符 *）
    • last_name：（字符串，可选）按姓氏筛选（支持通配符 *）
  • 基于时间的筛选条件：
    • modified_before：（字符串，可选）按修改日期筛选（ISO 8601）
    • modified_since：（字符串，可选）按修改日期筛选（ISO 8601）
  • 分页：
    • page：（数字，可选）页码（默认值：1）
    • per_page：（数字，可选）每页结果数（默认值：50，最大值：50）

• get_user：按 ID 获取特定用户

  • 必需参数：
    • id：（数字）要获取的用户 ID

• get_current_user：获取当前经过身份验证的用户

  • 无需参数
  • 返回详细的用户信息，包括：
    • 基本个人资料信息
    • 公司详情
    • PTO 余额
    • 权限
    • 自定义字段

• get_groups：获取 QuickBooks Time 中的所有群组

  • 可选参数：
    • ids：（数字数组）按特定群组 ID 筛选
    • active：（字符串）按状态筛选："yes"、"no"、"both"（默认值："yes"）
    • manager_ids：（数字数组）按经理用户 ID 筛选群组
    • supplemental_data：（字符串）是否包含补充数据："yes"、"no"（默认值："yes"）
  • 返回群组信息，包括：
    • 基本群组详情
    • 经理分配情况
    • 工时表设置
    • 工时条目设置
    • 休息设置

项目管理工具

• get_projects：获取项目并进行筛选

  • 可选参数：
    • ids：（数字数组）按特定项目 ID 筛选
    • active：（字符串）按状态筛选："yes"、"no"、"both"（默认值："yes"）
    • client_id：（数字）按客户 ID 筛选
    • jobcode_id：（数字）按关联的工作代码 ID 筛选
    • modified_before：（字符串）按修改日期筛选（ISO 8601）
    • modified_since：（字符串）按修改日期筛选（ISO 8601）
    • page：（数字）页码（默认值：1）
    • per_page：（数字）每页结果数（默认值：50，最大值：50）
  • 返回项目信息，包括：
    • 基本项目详情
    • 客户和工作代码关联信息
    • 预算信息
    • 日期和状态
    • 自定义字段

• get_project_activities：获取项目活动日志

  • 可选参数：
    • project_ids：（数字数组）将活动筛选为特定项目
    • user_ids：（数字数组）按特定用户筛选活动
    • activity_types：（字符串数组）按活动类型筛选："status_change"、"note_added"、"budget_change"、"date_change"、"custom_field_change"
    • modified_before：（字符串）按修改日期筛选（ISO 8601）
    • modified_since：（字符串）按修改日期筛选（ISO 8601）
    • page：（数字）页码（默认值：1）
    • per_page：（数字）每页结果数（默认值：50，最大值：50）
  • 返回活动信息，包括：
    • 活动类型和详情
    • 执行更改的用户
    • 旧值和新值
    • 时间戳

报告工具

• get_current_totals：获取包含班次和当日总计的当前总计快照

  • 可选参数：
    • user_ids：（数字数组）将总计筛选为指定用户
    • group_ids：（数字数组）筛选特定组中用户的总计
    • jobcode_ids：（数字数组）将总计筛选为指定工作代码
    • customfield_query：（字符串）按自定义字段值筛选，格式为：<customfield_id>||
  • 返回：
    • 活跃工时记录的实时总计
    • 时长和开始时间
    • 关联的工作代码和用户信息
    • 自定义字段值

• get_payroll：获取工资报告

  • 必需参数：
    • start_date：（字符串）工资周期的开始日期（YYYY-MM-DD）
    • end_date：（字符串）工资周期的结束日期（YYYY-MM-DD）
  • 可选参数：
    • user_ids：（数字数组）将工资数据筛选为指定用户
    • group_ids：（数字数组）筛选特定组中用户的工资数据
    • include_zero_time：（布尔值）包含没有工时记录的用户（默认值：false）
  • 返回：
    • 按类型统计的总工时（常规、加班、双倍工时、带薪休假）
    • 每位用户的每日明细
    • 工时表数量

• get_payroll_by_jobcode：获取按工作代码分组的工资报告

  • 必需参数：
    • start_date：（字符串）工资周期的开始日期（YYYY-MM-DD）
    • end_date：（字符串）工资周期的结束日期（YYYY-MM-DD）
  • 可选参数：
    • user_ids：（数字数组）将工资数据筛选为指定用户
    • group_ids：（数字数组）筛选特定组中用户的工资数据
    • jobcode_ids：（数字数组）将工资数据筛选为指定工作代码
    • jobcode_type：（字符串）按类型筛选："regular"、"pto"、"paid_break"、"unpaid_break"
    • include_zero_time：（布尔值）包含没有工时记录的工作代码（默认值：false）
  • 返回：
    • 按工作代码统计的工时总计
    • 每个工作代码中按用户划分的明细
    • 每个工作代码的每日总计

• get_project_report：获取包含工时记录的详细项目报告

  • 必需参数：
    • start_date：（字符串）开始日期，格式为 YYYY-MM-DD
    • end_date：（字符串）结束日期，格式为 YYYY-MM-DD
  • 可选参数：
    • user_ids：（数字数组）按指定用户筛选工时记录
    • group_ids：（数字数组）按指定组筛选工时记录
    • jobcode_ids：（数字数组）按指定工作代码筛选工时记录
    • jobcode_type：（字符串）按类型筛选："regular"、"pto"、"unpaid_break"、"paid_break"、"all"（默认值："all"）
    • customfielditems：（对象）按自定义字段值筛选，格式为：{"customfield_id": ["value1", "value2"]}
  • 返回：
    • 项目工时总计
    • 按用户和组划分的明细
    • 根据条件筛选的工时记录

其他工具

• get_custom_fields：获取配置在工时卡上的自定义跟踪字段

  • 参数：
    • ids：（数字数组）按指定自定义字段 ID 筛选
    • active：（字符串）按状态筛选："yes"、"no"、"both"
    • applies_to：（字符串）按适用类型筛选："timesheet"、"jobcode"、"user"
    • value_type：（字符串）按值类型筛选："managed-list"、"free-form"
    • page：（数字）页码
    • limit：（数字）每页结果数

• get_last_modified：获取对象的最后修改时间戳

  • 参数：
    • types：（字符串数组）要检查的对象类型（例如，["timesheets", "jobcodes", "users"]）

• get_notifications：获取通知

  • 参数：
    • page：（数字）页码
    • limit：（数字）每页结果数

• get_managed_clients：获取受管理的客户端

  • 参数：
    • page：（数字）页码
    • limit：（数字）每页结果数

运行服务

python main.py

服务将启动，并通过 stdin/stdout 监听 JSON-RPC 请求。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

贡献

欢迎贡献！欢迎提交 Pull Request。鉴于本项目是在 AI 协助下开发的，社区的意见对于改进和维护代码库尤其重要。

支持

如有问题或功能请求，请使用 GitHub issues 页面，或直接通过 github.com/aallsbury 联系我。