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 access token 및 순환되는 refresh token.

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 — Hubstaff가 refresh token으로 발급하는 Personal Access Token;

   • HUBSTAFF_ACCESS_TOKEN — 임시 access token.

PAT에는 hubstaff:read 및 tasks:read scope가 필요합니다. 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는 한 요청으로 최대 7일 간격만 반환합니다. hubstaff_task_hours가 범위를 직접 분할합니다.

• 상세 활동 기록은 최대 약 6개월까지 사용할 수 있습니다.

• 댓글은 Hubstaff Tasks API v1에 속하며 일부 요금제 또는 tasks:read scope가 없으면 반환되지 않을 수 있습니다. 이 경우 도구는 작업 응답에 포함된 댓글도 확인하고 빈 결과 대신 이해하기 쉬운 오류를 반환합니다.

공식 문서: Hubstaff API, authentication, tasks, activities.