tsheets-mcp

用于 TSheets (QuickBooks Time) 的 MCP 服务器——Intuit 的时间跟踪、排班和 PTO（带薪休假）平台。将完整的 TSheets 公共 REST API v1 公开为 MCP 工具。

概述

• 无状态 HTTP 服务。任何凭据都不会被持久化——每个请求通过请求头提供自己的访问令牌，该令牌仅在该单个请求的生命周期内使用。

• 支持并发请求；按请求的凭据隔离通过 Python contextvars 实现，而非全局/共享客户端实例。

• 入口点：POST /mcp（MCP 协议）和 GET /health（健康检查）。

• 默认端口：8080（可通过 MCP_HTTP_PORT 配置）。

• TSheets API 中任何地方都不存在路径模板参数——每个标识符（ids、user_id 等）都作为查询字符串参数传递，即使是单资源查询也是如此。这是 API 设计的真实特征，而非本服务器所做的简化。

Related MCP server: Timesheet MCP Server

范围

15 个工具，从最初 85 个工具的全 API 构建（2026-08-04）中精简而来。MSPbots 为该供应商存储的集成配置恰好调用 6 个端点（Effective Settings、Jobcodes、Users、Customfielditem User Filters、Timesheets、Custom Fields——全部为 GET，只读）。根据“实际使用 + 同类核心 CRUD”的范围决策，此构建完整保留这 6 个类别——effective_settings（1 个，只读，该资源不存在 CRUD 动词）、custom_field_item_user_filters（1 个，同上）、jobcodes（3 个：create/retrieve/update）、users（3 个：create/retrieve/update）、timesheets（4 个：create/retrieve/update/delete）、custom_fields（3 个：create/retrieve/update）——共 15 个工具。原始 85 个工具构建中的其他所有类别（Reports、Files、Time Off Requests（+ Entries）、Schedule Events（+ Calendars）、Reminders、Projects（+ Notes/Activities/Activity Replies/Activity Read Times）、Notifications、Locations（+ Maps）、Jobcode Assignments、Groups、Estimates（+ Items）、Custom Field Items（+ Filters + Jobcode Filters）、Geolocations、Timesheets Deleted、Managed Clients、Last Modified、Invitations、Geofence Configs、Current User——28 个类别，约 70 个工具）因 MSPbots 未使用而被完全移除。

保留工具的数据最初是通过克隆 TSheets 文档自己的 GitHub 仓库（https://github.com/tsheetsteam/api_docs）并解析每个端点的 Markdown/ERB 分部文件（source/includes/APIReference/<Category>/_*.md.erb）以获取其 HTTP 方法、路径和参数表而提取的——与本计划中其他大型 API 供应商（ConnectSecure、Dynu、Jira Data Center、Opsgenie）使用的结构化提取然后代码生成方法相同。如果之后需要某个已移除的类别，可以用同样的方式重新解析同一数据源。

身份验证

TSheets 使用通过供应商自己的 OAuth/API 应用流程获取的静态访问令牌（请参阅从其自身集成配置链接的 MSPbots 内部 KB 文章）。MSPbots 自己的集成约定以 Authorization: Bearer <accessToken> 的形式发送此令牌，与 TSheets 自己记录的格式一致，本服务器完全按该方式转发。

HEADER 授权参数说明

缺少该请求头时返回 401：

{
  "error": "Missing credentials",
  "message": "This server requires the X-TSheets-Access-Token header",
  "required_headers": ["X-TSheets-Access-Token"],
  "optional_headers": []
}

环境变量

MCP 端点

• POST /mcp — MCP 协议（可流式 HTTP 传输）

• GET /health — 健康检查，精确返回 {"status": "ok"}。这是一个纯本地探针——它不会调用 TSheets API，因此 TSheets 故障永远不会将容器标记为不健康。

错误与分页

• 工具错误以带内 JSON 信封形式返回（而非抛出的异常或协议级错误）：{"error": {"code": "...", "message": "...", "retryable": true|false}}。code 为 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error 之一，根据上游 HTTP 状态映射。

• 对 TSheets API 的出站调用使用 5 秒连接 / 30 秒读取超时，在 429/5xx 时以封顶指数退避重试最多 3 次（遵循 Retry-After），并在进程生命周期内复用单个连接池。

• 每个 retrieve_* 工具的 limit 参数默认值为 50，如果调用方要求更多，则会被限制为 TSheets 自己记录的每页最大值 200（TSheets 自己的 API 也默认/最大为 200，因此两个上限在此一致）。

工具列表

工具名称格式为 tsheets_<category>_<operation>，源自源文档中每个操作的 ## Heading（例如 timesheets 类别中的 "Retrieve Timesheets" → tsheets_timesheets_retrieve_timesheets）。一些 retrieve 过滤器参数被记录为“必需（除非设置了 X、Y 或 Z）”——这是一种 N 选一的要求，无法干净地表达为单个硬性必需的 Python 参数，因此这些参数被建模为可选，OR 约束在工具自己的 docstring 中明确说明。create/update 端点的 body 参数作为通用 dict 接受——TSheets 自己的约定将这些包装在 {"data": [ {...}, ... ]} 中（每次调用批量创建/更新最多 50 个对象），每个工具都有文档说明。

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tsheets_jobcodes_retrieve_jobcodes",
      "arguments": {}
    }
  }'

线上实测（2026-07-30）：第一个测试访问令牌已过期（401 invalid_grant，通过直接 curl 确认结果一致——有关该次运行发现的问题，请参阅下面的错误说明）。随后，使用第二个新签发的访问令牌通过此运行中的服务器进行了端到端测试，并返回了真实账户数据：tsheets_current_user_retrieve_the_current_user 返回了实际的当前用户记录（姓名、权限、PTO 余额）以及补充的工作代码数据，tsheets_jobcodes_retrieve_jobcodes（与 MSPbots 自己配置的 6 个端点之一匹配）返回了真实的工作代码记录。两者均确认完整的请求/认证/响应管道能够针对线上 API 正常工作。

自测期间修复的错误：最初的 _raise_for_status 错误解析器假设 TSheets 总是将错误详情嵌套为 {"error": {"message": "..."}}，但 TSheets 实际上对认证失败返回的是 OAuth 风格的扁平结构 {"error": "invalid_grant", "error_description": "..."}——对字符串 "invalid_grant" 调用 .get() 会因 'str' object has no attribute 'get' 而崩溃。在认为此服务器完成之前，使用第一个（已过期的）测试令牌发现并修复了此问题。

API 参考

• 概述：https://tsheetsteam.github.io/api_docs/

• 源代码（含官方 Postman 集合）：https://github.com/tsheetsteam/api_docs

已知差距

• 2026-08-04 从 85 个工具缩减为 15 个。 根据早期的范围决策，最初的构建覆盖了 34 个类别的完整公共 API。后来的范围决策将其缩减为恰好是 MSPbots 实际使用的 6 个类别（全部完整保留——无需按类别裁剪，因为没有哪个类别超过几个工具）——有关被移除的 28 个类别（约 70 个工具）的完整列表，请参阅上面的“范围”部分。如果之后需要某个被移除的类别，可以按照生成保留工具的相同方式重新解析源文档（https://github.com/tsheetsteam/api_docs）。

• 根据供应商自己的文档，tsheets_timesheets_delete_timesheets 永久删除工时表记录——请将其视为破坏性/不可逆操作，并在调用前与人工确认。其他保留的 create/update 工具也会修改真实的 TSheets 数据（工作代码、用户、自定义字段）。

• N 选一的“必填”过滤器组被建模为全部可选——多个 Retrieve 端点将某个参数记录为“必填（除非设置了 X、Y 或 Z）”；在普通的函数签名中无法将其作为真正的约束来强制执行，因此所有这些参数在工具签名中都是可选的，而“或”约束则在文档字符串中明确说明。调用方必须根据文档中的约束至少提供一个参数，否则线上 API 将拒绝该请求。

• body 参数是未类型化的（dict），而非完全建模——TSheets 自己的文档展示了按类型区分的字段变体（例如，在同一个 data 数组中，“Regular Timesheets”与“Manual Timesheets”具有不同的必填字段），这些无法干净地映射到固定的类型化参数上；供应商自己的参考文档（上面已链接）记录了每个资源的确切 schema。