Hubstaff MCP Server

Удалённый read-only MCP-сервер для Hubstaff Time Tracking API v2 и Hubstaff Tasks API v1. Он предоставляет задачи, свежие изменения, комментарии и агрегированное время по задачам через Streamable HTTP.

Сервер включает встроенный OAuth 2.1 authorization server для ChatGPT Developer mode: 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 — комментарии задачи, если endpoint доступен тарифу и токену.

Все инструменты только читают данные.

Related MCP server: timedoctor-mcp

Настройка

1. Скопируйте .env.example в .env.

2. Укажите MCP_AUTH_TOKEN длиной не менее 32 символов.

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 — Personal Access Token, который Hubstaff выдаёт как refresh token;

   • HUBSTAFF_ACCESS_TOKEN — временный access token.

Для PAT нужны scopes hubstaff:read и tasks:read. Hubstaff вращает refresh token при каждом обмене; сервер атомарно сохраняет актуальную пару в /data/token.json внутри именованного Docker volume. Исходный ключ остаётся только в .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 добавьте URL https://hubstuff-mcp.copperdiver.studio/mcp с OAuth/DCR. Во время первого подключения введите OAUTH_USERNAME и OAUTH_PASSWORD из серверного .env.

Проверка доступности без секрета:

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

Ограничения Hubstaff

• Activity API отдаёт интервалы не более чем за 7 дней одним запросом; hubstaff_task_hours сам разбивает диапазон на части.

• История детальной активности доступна максимум примерно за 6 месяцев.

• Комментарии относятся к Hubstaff Tasks API v1 и могут не отдаваться на некоторых тарифах или без scope tasks:read. В этом случае инструмент также проверяет комментарии, встроенные в ответ задачи, и возвращает понятную ошибку вместо пустого результата.

Официальная документация: Hubstaff API, authentication, tasks, activities.