Hubstaff MCP Server

Hubstaff Time Tracking API v2 と Hubstaff Tasks API v1 用のリモート読み取り専用 MCP サーバー。Streamable HTTP を介して、タスク、最近の変更、コメント、タスクごとの集計時間を提供します。

サーバーには、ChatGPT Developer mode 用の組み込み OAuth 2.1 authorization server が含まれています: DCR、authorization code、PKCE S256、audience-bound JWT access tokens、およびローテーションされる refresh tokens。

MCP tools

• 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 が refresh token として発行する Personal Access Token;

   • HUBSTAFF_ACCESS_TOKEN — 一時的な access token。

PAT にはスコープ hubstaff:read と tasks:read が必要です。Hubstaff は交換のたびに refresh token をローテーションします。サーバーは、名前付き Docker volume 内の /data/token.json に最新のペアをアトミックに保存します。元のキーは .env にのみ残り、.env は Git と Docker build context から除外されています。

起動:

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 ページで OAuth/DCR 付きの URL https://hubstuff-mcp.copperdiver.studio/mcp を追加します。初回接続時に、サーバーの .env の OAUTH_USERNAME と OAUTH_PASSWORD を入力します。

シークレットなしでの可用性チェック:

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

Hubstaff の制限

• Activity API は 1 回のリクエストで最大 7 日分の間隔を返します。hubstaff_task_hours は範囲を自動的に分割します。

• 詳細なアクティビティ履歴は最大約 6 か月分のみ利用可能です。

• コメントは Hubstaff Tasks API v1 に属し、一部のプランやスコープ tasks:read がない場合は返されない場合があります。この場合、ツールはタスク応答に埋め込まれたコメントも確認し、空の結果の代わりにわかりやすいエラーを返します。

公式ドキュメント: Hubstaff API、authentication、tasks、activities。