星战科技xingzhan.cloud
返回市场
qb时间mcp服务器

qb时间mcp服务器

作者：aallsbury8 星标更新：2025-06-20
安装使用来源：spider==github.com

项目介绍

QuickBooks Time MCP Server (V2 更新)

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

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

我很乐意帮助改进这个项目！很高兴终于能够回馈一些东西！

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

  1. 安装依赖项：
pip install -r requirements.txt
  1. 创建一个.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"
      }
    }
  }
}

可用工具

工作代码工具

  • 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: 获取当前认证用户

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

  • 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>|<op>|<value>
    • 返回：
      • 活动时间条目的实时总计
      • 持续时间和开始时间
      • 关联的工作代码和用户信息
      • 自定义字段值

  • 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。鉴于该项目是在人工智能的帮助下开发的，社区的投入对于改进和维护代码库尤为重要。

支持

对于问题和功能请求，请使用GitHub问题页面或直接联系我在github.com/aallsbury。 </中文翻译>