qb-time-mcp-server

QuickBooks Time MCP 服务器（V2 更新）

这是一个组合式 MCP 服务器，可通过单一界面访问所有 QuickBooks Time API 功能。它结合了四个独立服务器的功能：

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

我很乐意帮忙改进这个项目！很高兴终于能回馈大家了！

整个项目都是使用人工智能（Anthropic、OpenAI、Llama/META）开发和发布的，因为我个人很难在没有他人帮助的情况下编写大量代码。尽管我已尽一切努力确保质量和功能，但仍可能存在一些缺陷或需要改进的地方。欢迎社区提供任何反馈、更正或建议。

1. 安装依赖项：

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

Claude桌面配置

要将此服务器与 Claude Desktop 一起使用，您需要在 Claude Desktop 设置中进行配置。以下是示例配置：

可用工具

JobCode 工具

• get_jobcodes ：使用高级过滤选项获取职位代码
  • 基本过滤器：
    • ids ：（数字数组，可选）以逗号分隔的职位代码 ID 列表
    • name ：（字符串，可选）按职位代码名称过滤，支持从字符串开始的通配符（*）匹配
    • active ：（字符串，可选）按状态过滤：“是”、“否”、“两者”（默认值：“是”）
  • 类型和层次结构过滤器：
    • type ：（字符串，可选）按类型过滤：“regular”、“pto”、“paid_break”、“unpaid_break”、“all”（默认值：“regular”）
    • parent_ids ：（数字数组，可选）按父级职位代码 ID 进行筛选。特殊值：0（仅限顶层职位），-1（所有层级）
  • 附加过滤器：
    • customfields ：（布尔值，可选）在响应中包含自定义字段
    • modified_before ：（字符串，可选）按修改日期过滤（ISO 8601 格式）
    • modified_since ：（字符串，可选）按修改日期过滤（ISO 8601 格式）
    • page ：（数字）分页的页码
    • limit ：（数字）每页结果数（最多 200 条）
• get_jobcode ：通过 ID 获取特定的职位代码
  • 必需参数：
    • id ：（数字）要检索的职位代码的 ID
• get_jobcode_hierarchy ：获取完整的职位代码层次结构
  • 参数：
    • parent_ids ：（数字数组，可选）按父级 ID 过滤。值：0（顶级）、-1（全部）或特定 ID
    • active ：（字符串，可选）按状态过滤：“是”、“否”、“两者”（默认值：“是”）
    • 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 ：（字符串）按当前工作状态过滤：“是”、“否”、“两者”（默认值：“否”）
    • jobcode_type ：（字符串）按类型过滤：“regular”、“pto”、“paid_break”、“unpaid_break”、“all”（默认值：“all”）
    • page : (number) 页码
    • limit ：（数量）每页结果
• get_timesheet ：通过 ID 获取特定时间表
  • 必需参数：
    • id ：（数字）要检索的时间表的 ID
• get_current_timesheets ：获取当前活动的时间表
  • 必需参数：
    • on_the_clock ：（字符串）必须设置为“yes”
  • 可选参数：
    • user_ids ：（数字数组）过滤特定用户的活动时间表
    • group_ids ：（数字数组）为特定组中的用户过滤活动时间表
    • jobcode_ids ：（数字数组）过滤特定职位代码的活动时间表
    • supplemental_data ：（字符串）包括补充数据：“是”、“否”（默认值：“是”）

用户工具

• get_users ：通过过滤获取所有用户
  • 用户识别过滤器：
    • ids ：（数字数组，可选）按特定用户 ID 进行过滤
    • not_ids ：（数字数组，可选）排除特定用户 ID
    • employee_numbers ：（数字数组，可选）按员工编号过滤
    • usernames ：（字符串数组，可选）按特定用户名过滤
  • 组过滤器：
    • group_ids ：（数字数组，可选）按组成员身份进行过滤
    • not_group_ids ：（数字数组，可选）从特定组中排除用户
  • 状态和识别过滤器：
    • payroll_ids ：（字符串数组，可选）按工资单识别号过滤
    • active ：（字符串，可选）按状态过滤：“是”、“否”、“两者”（默认值：“是”）
  • 名称过滤器：
    • 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 ：（字符串）按状态过滤：“是”、“否”、“两者”（默认值：“是”）
    • manager_ids ：（数字数组）按经理用户 ID 过滤组
    • supplemental_data ：（字符串）包括补充数据：“是”、“否”（默认值：“是”）
  • 返回组信息包括：
    • 基本群组详情
    • 经理任务
    • 时间表设置
    • 时间输入设置
    • 中断设置

项目管理工具

• get_projects ：通过过滤获取项目
  • 可选参数：
    • ids ：（数字数组）按特定项目 ID 进行过滤
    • active ：（字符串）按状态过滤：“是”、“否”、“两者”（默认值：“是”）
    • 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 ：（字符串）按状态过滤：“是”、“否”、“两者”
    • applies_to ：（字符串）按应用程序类型过滤：“timesheet”、“jobcode”、“user”
    • value_type ：（字符串）按值类型过滤：“managed-list”、“free-form”
    • page : (number) 页码
    • limit ：（数量）每页结果
• get_last_modified ：获取对象的最后修改时间戳
  • 参数：
    • types ：（字符串数组）要检查的对象类型（例如，[“timesheets”、“jobcodes”、“users”]）
• get_notifications ：获取通知
  • 参数：
    • page : (number) 页码
    • limit ：（数量）每页结果
• get_managed_clients ：获取托管客户端
  • 参数：
    • page : (number) 页码
    • limit ：（数量）每页结果

运行服务器

服务器将启动并监听 stdin/stdout 上的 JSON-RPC 请求。

执照

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

贡献

欢迎贡献！请随时提交 Pull 请求。鉴于该项目是在 AI 辅助下开发的，社区意见对于代码库的改进和维护尤为重要。

支持

对于问题和功能请求，请使用 GitHub 问题页面或直接通过 github.com/aallsbury 与我联系。