QuickBooks Time MCP 服务器 (V2 更新)

这是一个组合的 MCP 服务器，通过单一接口提供对所有 QuickBooks Time API 功能的访问。它结合了四个独立服务器的功能：

1. JobCode 工具
2. 报表 & 核心工具
3. 时间表工具
4. 用户工具

我非常希望能够改进这个项目！很高兴最终能够回馈一些东西！

整个项目都是使用人工智能（Anthropic、OpenAI、Llama/META）开发和发布的，因为我个人在没有帮助的情况下无法编写太多代码。虽然已尽一切努力确保质量和功能，但可能存在不完善之处或需要改进的地方。我欢迎来自社区的任何反馈、更正或建议。

1. 安装依赖项：

pip install -r requirements.txt

2. 创建一个包含您的 QuickBooks Time 访问令牌的 .env 文件：

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: (数字数组) 按特定 jobcode 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: (数字数组) 过滤特定 jobcode 的活动时间表
    • 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: (数字) 按关联的 jobcode ID 过滤
    • modified_before: (字符串) 按修改日期过滤 (ISO 8601)
    • modified_since: (字符串) 按修改日期过滤 (ISO 8601)
    • page: (数字) 页码（默认：1）
    • per_page: (数字) 每页结果数（默认：50，最大：50）
  • 返回项目信息，包括：
    • 基本项目详细信息
    • 客户和 jobcode 关联
    • 预算信息
    • 日期和状态
    • 自定义字段

• 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: (数字数组) 过滤特定 jobcode 的总计
    • customfield_query: (字符串) 按自定义字段值过滤，格式为：<customfield_id>|<op>|<value>
  • 返回：
    • 活动时间条目的实时总计
    • 持续时间和开始时间
    • 关联的 jobcode 和用户信息
    • 自定义字段值

• get_payroll: 获取工资单报表

  • 必需参数：
    • start_date: (字符串) 工资期的开始日期 (YYYY-MM-DD)
    • end_date: (字符串) 工资期的结束日期 (YYYY-MM-DD)
  • 可选参数：
    • user_ids: (数字数组) 过滤特定用户的工资单
    • group_ids: (数字数组) 过滤特定组中用户的工资单
    • include_zero_time: (布尔值) 包含没有时间条目的用户（默认：false）
  • 返回：
    • 按类型（正常、加班、双倍时间、PTO）的总时间
    • 每个用户的每日细分
    • 时间表计数

• get_payroll_by_jobcode: 获取按 jobcode 分组的工资单报表

  • 必需参数：
    • start_date: (字符串) 工资期的开始日期 (YYYY-MM-DD)
    • end_date: (字符串) 工资期的结束日期 (YYYY-MM-DD)
  • 可选参数：
    • user_ids: (数字数组) 过滤特定用户的工资单
    • group_ids: (数字数组) 过滤特定组中用户的工资单
    • jobcode_ids: (数字数组) 过滤特定 jobcode 的工资单
    • jobcode_type: (字符串) 按类型过滤："regular"、"pto"、"paid_break"、"unpaid_break"
    • include_zero_time: (布尔值) 包含没有时间条目的 jobcode（默认：false）
  • 返回：
    • 按 jobcode 的时间总计
    • 每个 jobcode 中用户的细分
    • 每个 jobcode 的每日总计

• get_project_report: 获取带有时间条目的详细项目报表

  • 必需参数：
    • start_date: (字符串) YYYY-MM-DD 格式的开始日期
    • end_date: (字符串) YYYY-MM-DD 格式的结束日期
  • 可选参数：
    • user_ids: (数字数组) 按特定用户过滤时间条目
    • group_ids: (数字数组) 按特定组过滤时间条目
    • jobcode_ids: (数字数组) 按特定 jobcode 过滤时间条目
    • 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 问题页面或直接通过 github.com/aallsbury 与我联系。