Hubstaff MCP Server

Servidor MCP remoto de solo lectura para la API de seguimiento de tiempo de Hubstaff v2 y la API de tareas de Hubstaff v1. Proporciona tareas, cambios recientes, comentarios y tiempo agregado por tarea a través de HTTP Streamable.

El servidor incluye un servidor de autorización OAuth 2.1 integrado para el modo de desarrollador de ChatGPT: DCR, código de autorización, PKCE S256, tokens de acceso JWT vinculados a la audiencia y tokens de actualización rotativos.

Herramientas MCP

• hubstaff_list_organizations — organizaciones disponibles y sus ID.

• hubstaff_list_tasks — tareas de la organización con filtros.

• hubstaff_get_task — detalles de la tarea de seguimiento de tiempo.

• hubstaff_recent_updates — tareas y registros de tiempo modificados recientemente.

• hubstaff_task_hours — horas por tarea y desglose por usuarios.

• hubstaff_tasks_list_projects — proyectos de Hubstaff Tasks.

• hubstaff_tasks_list_project_tasks — tareas del tablero del proyecto.

• hubstaff_tasks_get_task — detalles de la tarea de Hubstaff Tasks.

• hubstaff_tasks_list_comments — comentarios de la tarea, si el endpoint está disponible según el plan y el token.

Todas las herramientas solo leen datos.

Related MCP server: timedoctor-mcp

Configuración

1. Copie .env.example a .env.

2. Especifique MCP_AUTH_TOKEN con una longitud de al menos 32 caracteres.

3. Para ChatGPT, especifique OAUTH_ISSUER, OAUTH_USERNAME, OAUTH_PASSWORD y OAUTH_SIGNING_SECRET. El estado de OAuth se guarda en /data/oauth-state.json.

4. Elija una opción de autorización de Hubstaff:

   • HUBSTAFF_ORGANIZATION_TOKEN (hsoat_...) — la opción recomendada para un servidor que funciona continuamente;

   • HUBSTAFF_REFRESH_TOKEN — Token de Acceso Personal que Hubstaff emite como token de actualización;

   • HUBSTAFF_ACCESS_TOKEN — token de acceso temporal.

Para PAT se necesitan los alcances hubstaff:read y tasks:read. Hubstaff rota el token de actualización en cada intercambio; el servidor guarda atómicamente el par actualizado en /data/token.json dentro de un volumen Docker con nombre. La clave original permanece solo en .env, y .env está excluido de Git y del contexto de compilación de Docker.

Ejecución:

npm ci
npm run build
npm test
npm start

Docker:

docker compose up -d --build

Conexión del cliente MCP

URL:

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

Para un cliente MCP normal, puede usar el encabezado de servicio:

Authorization: Bearer <MCP_AUTH_TOKEN>

ChatGPT se conecta mediante OAuth automáticamente. El servidor publica:

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

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

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

En ChatGPT, habilite Settings → Security and login → Developer mode, luego en la página de Plugins agregue la URL https://hubstuff-mcp.copperdiver.studio/mcp con OAuth/DCR. Durante la primera conexión, ingrese OAUTH_USERNAME y OAUTH_PASSWORD del .env del servidor.

Verificación de disponibilidad sin secreto:

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

Limitaciones de Hubstaff

• La API de actividad devuelve intervalos de no más de 7 días por solicitud; hubstaff_task_hours divide automáticamente el rango en partes.

• El historial de actividad detallada está disponible como máximo aproximadamente durante 6 meses.

• Los comentarios pertenecen a la API de Hubstaff Tasks v1 y pueden no entregarse en algunos planes o sin el alcance tasks:read. En ese caso, la herramienta también verifica los comentarios integrados en la respuesta de la tarea y devuelve un error claro en lugar de un resultado vacío.

Documentación oficial: Hubstaff API, authentication, tasks, activities.