QuickBooks Time MCP 服务器 (V2 更新)

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

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

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

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

1. 安装依赖项：

pip install -r requirements.txt

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

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Claude桌面配置

要使用Claude桌面与此服务器配合，您需要在Claude桌面设置中进行配置。以下是一个示例配置：

{
  "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"
      }
    }
  }
}

可用工具

工作代码工具

• get_jobcodes: 使用高级过滤选项获取工作代码

  • 基本过滤器:
    • ids: (数字数组，可选) 逗号分隔的工作代码ID列表
    • name: (字符串，可选) 按工作代码名称过滤，支持从字符串开头开始的通配符(*)匹配
    • active: (字符串，可选) 按状态过滤: "yes", "no", "both" (默认: "yes")
  • 类型和层次结构过滤器:
    • 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: (字符串，可选) 按状态过滤: "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: (字符串) 按自定义字段值过滤，格式为：<自定义字段ID>|<操作符>|<值>
  • 返回：
    • 实时活动时间条目的总计
    • 持续时间和开始时间
    • 相关的工作代码和用户信息
    • 自定义字段值

• 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: 按工作代码分组获取工资报告

  • 必需参数：
    • 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: (对象) 按自定义字段值过滤，格式为：{"自定义字段ID": ["值1", "值2"]}
  • 返回：
    • 项目时间总计
    • 按用户和组细分
    • 基于标准过滤的时间条目

额外工具

• 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。