Hubstaff MCP Server

A remote read-only MCP server for the Hubstaff Time Tracking API v2 and Hubstaff Tasks API v1. It provides tasks, recent updates, comments, and aggregated time by task via Streamable HTTP.

The server includes a built-in OAuth 2.1 authorization server for ChatGPT Developer mode: DCR, authorization code, PKCE S256, audience-bound JWT access tokens, and rotating refresh tokens.

MCP tools

• hubstaff_list_organizations — available organizations and their IDs.

• hubstaff_list_tasks — organization tasks with filters.

• hubstaff_get_task — Time Tracking task details.

• hubstaff_recent_updates — recently updated tasks and time entries.

• hubstaff_task_hours — hours per task and breakdown by users.

• hubstaff_tasks_list_projects — Hubstaff Tasks projects.

• hubstaff_tasks_list_project_tasks — project board tasks.

• hubstaff_tasks_get_task — Hubstaff Tasks task details.

• hubstaff_tasks_list_comments — task comments, if the endpoint is available to the plan and token.

All tools only read data.

Related MCP server: timedoctor-mcp

Setup

1. Copy .env.example to .env.

2. Set MCP_AUTH_TOKEN to at least 32 characters.

3. For ChatGPT, provide OAUTH_ISSUER, OAUTH_USERNAME, OAUTH_PASSWORD, and OAUTH_SIGNING_SECRET. The OAuth state is stored in /data/oauth-state.json.

4. Choose one Hubstaff authorization option:

   • HUBSTAFF_ORGANIZATION_TOKEN (hsoat_...) — the recommended option for an always-running server;

   • HUBSTAFF_REFRESH_TOKEN — a Personal Access Token that Hubstaff issues as a refresh token;

   • HUBSTAFF_ACCESS_TOKEN — a temporary access token.

PAT requires the hubstaff:read and tasks:read scopes. Hubstaff rotates the refresh token on every exchange; the server atomically saves the current pair to /data/token.json inside a named Docker volume. The original key remains only in .env, and .env is excluded from Git and the Docker build context.

Running:

npm ci
npm run build
npm test
npm start

Docker:

docker compose up -d --build

Connecting an MCP client

URL:

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

For a regular MCP client, you can use the service header:

Authorization: Bearer <MCP_AUTH_TOKEN>

ChatGPT connects via OAuth automatically. The server publishes:

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

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

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

In ChatGPT, enable Settings → Security and login → Developer mode, then on the Plugins page add the URL https://hubstuff-mcp.copperdiver.studio/mcp with OAuth/DCR. During the first connection, enter OAUTH_USERNAME and OAUTH_PASSWORD from the server's .env.

Availability check without a secret:

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

Hubstaff limitations

• The Activity API returns intervals of no more than 7 days per request; hubstaff_task_hours splits the range into parts itself.

• Detailed activity history is available for at most about 6 months.

• Comments belong to the Hubstaff Tasks API v1 and may not be returned on some plans or without the tasks:read scope. In that case, the tool also checks the comments embedded in the task response and returns a clear error instead of an empty result.

Official documentation: Hubstaff API, authentication, tasks, activities.