AI导哈

时间管理API服务器

QuickBooks Time MCP Server是一个整合了时间管理功能的API服务器，提供作业代码、时间表、用户和报告工具的统一接口，适用于企业时间跟踪和工资单处理。

  • by aallsbury
  • Python
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 aallsbury/qb-time-mcp-server

使用说明

QuickBooks时间MCP服务器（V2更新）

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

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

我很乐意帮助改进这个项目！很高兴终于能回馈社会了！

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

  1. 安装依赖项：
pip install -r requirements.txt
  1. 创建一个 .env 使用您的QuickBooks时间访问令牌的文件：
QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude桌面配置

要将此服务器与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：使用高级筛选选项获取作业代码

    • 基本过滤器：
      • ids：（数字数组，可选）以逗号分隔的作业代码ID列表
      • name：（string，可选）按作业代码名称筛选，支持通配符（*）从字符串开始匹配
      • active：（字符串，可选）按状态筛选：“yes”、“no”、“both”（默认值：“yes”）
    • 类型和层次过滤器：
      • type：（字符串，可选）按类型筛选
      • parent_ids：（数字数组，可选）按父作业代码ID筛选。特殊值：0（仅顶级），-1（所有级别）
    • 附加过滤器：
      • customfields：（boolean，可选）在响应中包含自定义字段
      • modified_before：（字符串，可选）按修改日期筛选（ISO 8601格式）
      • modified_since：（字符串，可选）按修改日期筛选（ISO 8601格式）
      • page：（number）分页页码
      • limit：（数量）每页结果（最多200个）

  • get_jobcode：通过ID获取特定的职位代码

    • 所需参数：
      • id：（number）要检索的作业代码的ID

  • get_jobcode_hierarchy：获取完整的作业代码层次结构

    • 参数：
      • parent_ids：（数字数组，可选）按父ID筛选。值：0（顶级）、-1（全部）或特定ID
      • active：（字符串，可选）按状态筛选：“yes”、“no”、“both”（默认值：“yes”）
      • type：（字符串，可选）按类型筛选
      • customfields：（boolean，可选）在响应中包含自定义字段

时间表工具

  • get_timesheets：通过筛选获取时间表

    • 必需参数（至少一个）：
      • ids：（数字数组）以逗号分隔的时间表ID列表
      • start_date：（string）返回此日期（YYYY-MM-DD）或之后的时间表
      • modified_before：（string）返回在此时间之前修改的时间表（ISO 8601）
      • modified_since：（string）返回自此时以来修改的时间表（ISO 8601）
    • 可选参数：
      • end_date：（string）返回此日期（YYYY-MM-DD）或之前的时间表
      • user_ids：（数字数组）按特定用户ID筛选
      • group_ids：（数字数组）按特定组ID筛选
      • jobcode_ids：（数字数组）按特定作业代码ID筛选（包括子项）
      • payroll_ids：（数字数组）按特定工资单ID筛选
      • on_the_clock：（string）按当前工作状态筛选：“是”、“否”、“两者都有”（默认：“否”）
      • jobcode_type：（string）按类型筛选：“常规”、“pto”、“paid_break”、”unpaid_breaks”、“all”（默认值：“all”）
      • page：（编号）页码
      • limit：（数量）每页结果

  • get_timesheet：按ID获取特定时间表

    • 所需参数：
      • id：（number）要检索的时间表的ID

  • get_current_timesheets：获取当前活动时间表

    • 所需参数：
      • on_the_clock：（string）必须设置为“yes”
    • 可选参数：
      • user_ids：（数字数组）筛选特定用户的活动时间表
      • group_ids：（数字数组）筛选特定组中用户的活动时间表
      • jobcode_ids：（数字数组）筛选特定职务代码的活动时间表
      • supplemental_data：（string）包括补充数据：“是”、“否”（默认值：“是）

用户工具

  • 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：（number）要检索的用户的ID

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

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

  • get_groups：从QuickBooks Time获取所有组

    • 可选参数：
      • ids：（数字数组）按特定组ID筛选
      • active：（string）按状态筛选：“yes”、“no”、“both”（默认值：“yes”）
      • manager_ids：（数字数组）按管理员用户ID筛选组
      • supplemental_data：（string）包括补充数据：“是”、“否”（默认值：“是）
    • 返回组信息，包括：
      • 基本组详细信息
      • 经理分配
      • 时间表设置
      • 时间输入设置
      • 中断设置

项目管理工具

  • get_projects：获取具有筛选功能的项目

    • 可选参数：
      • ids：（数字数组）按特定项目ID筛选
      • active：（string）按状态筛选：“yes”、“no”、“both”（默认值：“yes”）
      • client_id：（number）按客户端ID筛选
      • jobcode_id：（数字）按相关职务代码ID筛选
      • modified_before：（字符串）按修改日期筛选（ISO 8601）
      • modified_since：（字符串）按修改日期筛选（ISO 8601）
      • page：（number）页码（默认值：1）
      • per_page：（number）每页结果数（默认值：50，最大值：50）
    • 返回项目信息，包括：
      • 项目基本细节
      • 客户和职位代码协会
      • 预算信息
      • 日期和状态
      • 自定义字段

  • get_project_activities：获取项目活动日志

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

报告工具

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

    • 可选参数：
      • user_ids：（数字数组）筛选特定用户的总计
      • group_ids：（数字数组）筛选特定组中用户的总计
      • jobcode_ids：（数字数组）筛选特定职务代码的总计
      • customfield_query：（string）按自定义字段值过滤，格式为：<customfield_id>||
    • 退货：
      • 活动时间条目的实时总计
      • 持续时间和开始时间
      • 关联的作业代码和用户信息
      • 自定义字段值

  • get_payroll：获取工资单报告

    • 所需参数：
      • start_date：（string）支付期开始时间（YYYY-MM-DD）
      • end_date：（字符串）工资期结束（YYYY-MM-DD）
    • 可选参数：
      • user_ids：（数字数组）筛选特定用户的工资单
      • group_ids：（数字数组）为特定组中的用户筛选工资单
      • include_zero_time：（boolean）包括没有时间条目的用户（默认值：false）
    • 退货：
      • 按类型划分的总时间（常规、加班、双倍时间、PTO）
      • 每个用户的每日细分
      • 时间表计数

  • get_payroll_by_jobcode：获取按职务代码分组的工资单报告

    • 所需参数：
      • start_date：（string）支付期开始时间（YYYY-MM-DD）
      • end_date：（字符串）工资期结束（YYYY-MM-DD）
    • 可选参数：
      • user_ids：（数字数组）筛选特定用户的工资单
      • group_ids：（数字数组）为特定组中的用户筛选工资单
      • jobcode_ids：（数字数组）筛选特定职务代码的工资单
      • jobcode_type：（string）按类型筛选：“常规”、“pto”、“paid_break”、
      • include_zero_time：（boolean）包括没有时间条目的作业代码（默认值：false）
    • 退货：
      • 按作业代码统计的时间总计
      • 每个职位代码中按用户细分
      • 每个职位代码的每日总计

  • get_project_report：获取包含时间条目的详细项目报告

    • 所需参数：
      • start_date：（字符串）YYYY-MM-DD格式的开始日期
      • end_date：（字符串）YYYY-MM-DD格式的结束日期
    • 可选参数：
      • user_ids：（数字数组）按特定用户筛选时间条目
      • group_ids：（数字数组）按特定组筛选时间条目
      • jobcode_ids：（数字数组）按特定作业代码过滤时间条目
      • jobcode_type：（string）按类型筛选：“常规”、“pto”、“unpaid_break”、”all“（默认值：”all“）
      • customfielditems：（object）按自定义字段值筛选，格式为：{“customfield_id”：[“value1”，“value2”]}
    • 退货：
      • 项目时间总计
      • 按用户和组细分
      • 根据条件筛选时间条目

其他工具

  • get_custom_fields：在考勤卡上配置自定义跟踪字段

    • 参数：
      • ids：（数字数组）按特定自定义字段ID筛选
      • active：（string）按状态筛选：“yes”、“no”、“both”
      • applies_to：（字符串）按应用程序类型筛选：“时间表”、“作业代码”、“用户”
      • value_type：（string）按值类型筛选：“托管列表”、“自由格式”
      • page：（编号）页码
      • limit：（数量）每页结果

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

    • 参数：
      • types：（字符串数组）要检查的对象类型（例如，[“时间表”、“作业代码”、“用户”]）

  • get_notifications：获取通知

    • 参数：
      • page：（编号）页码
      • limit：（数量）每页结果

  • get_managed_clients：获取托管客户端

    • 参数：
      • page：（编号）页码
      • limit：（数量）每页结果

运行服务器

python main.py

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

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请随时提交拉取请求。鉴于这个项目是在人工智能的帮助下开发的，社区的投入对于改进和维护代码库尤其有价值。

支持

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

相关 MCP