Hubstaff MCP Server

用于 Hubstaff Time Tracking API v2 和 Hubstaff Tasks API v1 的远程只读 MCP 服务器。它通过 Streamable HTTP 提供任务、最新变更、评论以及按任务汇总的时间。

服务器内置用于 ChatGPT Developer mode 的 OAuth 2.1 授权服务器：DCR、授权码、PKCE S256、受众绑定的 JWT 访问令牌和轮换刷新令牌。

MCP 工具

• hubstaff_list_organizations — 可用组织及其 ID。

• hubstaff_list_tasks — 组织的任务及筛选条件。

• hubstaff_get_task — Time Tracking 任务详情。

• hubstaff_recent_updates — 最近变更的任务和时间记录。

• hubstaff_task_hours — 按任务查看工时并按用户细分。

• hubstaff_tasks_list_projects — Hubstaff Tasks 项目。

• hubstaff_tasks_list_project_tasks — 项目看板上的任务。

• hubstaff_tasks_get_task — Hubstaff Tasks 任务详情。

• hubstaff_tasks_list_comments — 任务的评论（如果端点对当前套餐和令牌可用）。

所有工具均只读取数据。

Related MCP server: timedoctor-mcp

配置

1. 将 .env.example 复制为 .env。

2. 设置长度至少为 32 个字符的 MCP_AUTH_TOKEN。

3. 对于 ChatGPT，请设置 OAUTH_ISSUER、OAUTH_USERNAME、OAUTH_PASSWORD 和 OAUTH_SIGNING_SECRET。OAuth 状态保存在 /data/oauth-state.json 中。

4. 选择以下一种 Hubstaff 授权方式：

   • HUBSTAFF_ORGANIZATION_TOKEN (hsoat_...) — 推荐用于持续运行的服务器；

   • HUBSTAFF_REFRESH_TOKEN — Hubstaff 颁发的 Personal Access Token，用作 refresh token；

   • HUBSTAFF_ACCESS_TOKEN — 临时 access token。

对于 PAT，需要 hubstaff:read 和 tasks:read 作用域。Hubstaff 在每次交换时都会轮换 refresh token；服务器会将最新的一对令牌原子化地保存到命名 Docker volume 内的 /data/token.json 中。原始密钥仅保留在 .env 中，并且 .env 已从 Git 和 Docker 构建上下文中排除。

运行：

npm ci
npm run build
npm test
npm start

Docker：

docker compose up -d --build

连接 MCP 客户端

URL：

https://hubstuff-mcp.copperdiver.studio/mcp

对于普通 MCP 客户端，可以使用服务头：

Authorization: Bearer <MCP_AUTH_TOKEN>

ChatGPT 通过 OAuth 自动连接。服务器发布：

• /.well-known/oauth-protected-resource

• /.well-known/oauth-authorization-server

• /oauth/register, /oauth/authorize, /oauth/token

在 ChatGPT 中启用 Settings → Security and login → Developer mode，然后在 Plugins 页面添加 URL https://hubstuff-mcp.copperdiver.studio/mcp 并选择 OAuth/DCR。首次连接时，输入服务器 .env 中的 OAUTH_USERNAME 和 OAUTH_PASSWORD。

无需密钥检查可用性：

curl https://hubstuff-mcp.copperdiver.studio/health

Hubstaff 限制

• Activity API 单次请求最多返回 7 天间隔的数据；hubstaff_task_hours 会自动拆分时间范围。

• 详细活动历史最多可获取约 6 个月。

• 评论属于 Hubstaff Tasks API v1，在某些套餐下或未授予 tasks:read 作用域时可能无法获取。这种情况下，工具还会检查任务响应中内嵌的评论，并返回易于理解的错误而不是空结果。

官方文档：Hubstaff API、authentication、tasks、activities。