tsheets-mcp

Servidor MCP para TSheets (QuickBooks Time) — la plataforma de seguimiento de tiempo, programación y PTO de Intuit. Expone la API REST pública v1 completa de TSheets como herramientas MCP.

Descripción general

• Servicio HTTP sin estado. Nunca se persisten credenciales: cada solicitud aporta su propio token de acceso mediante una cabecera, que se utiliza únicamente durante la vida de esa única solicitud.

• Admite solicitudes concurrentes; el aislamiento de credenciales por solicitud se realiza mediante contextvars de Python, no mediante una instancia de cliente global o compartida.

• Puntos de entrada: POST /mcp (protocolo MCP) y GET /health (comprobación de salud).

• Puerto predeterminado: 8080 (configurable mediante MCP_HTTP_PORT).

• No existen parámetros de plantilla de ruta en ningún lugar de la API de TSheets: cada identificador (ids, user_id, etc.) se pasa como parámetro de cadena de consulta, incluso para las consultas de un único recurso. Esta es una característica genuina del diseño de la API, no una simplificación realizada por este servidor.

Related MCP server: Timesheet MCP Server

Alcance

15 herramientas, reducidas a partir de una compilación original de 85 herramientas para toda la API (2026-08-04). La propia configuración de integración almacenada por MSPbots para este proveedor llama exactamente a 6 endpoints (Effective Settings, Jobcodes, Users, Customfielditem User Filters, Timesheets, Custom Fields — todos GET, de solo lectura). Según la decisión de alcance de «uso real + CRUD básico de la misma categoría», esta compilación mantiene exactamente esas 6 categorías completas: effective_settings (1, de solo lectura, no existen verbos CRUD para este recurso), custom_field_item_user_filters (1, igual), jobcodes (3: crear/recuperar/actualizar), users (3: crear/recuperar/actualizar), timesheets (4: crear/recuperar/actualizar/eliminar), custom_fields (3: crear/recuperar/actualizar) — 15 herramientas en total. Cualquier otra categoría de la compilación original de 85 herramientas (Reports, Files, Time Off Requests (+ Entries), Schedule Events (+ Calendars), Reminders, Projects (+ Notes/Activities/Activity Replies/Activity Read Times), Notifications, Locations (+ Maps), Jobcode Assignments, Groups, Estimates (+ Items), Custom Field Items (+ Filters + Jobcode Filters), Geolocations, Timesheets Deleted, Managed Clients, Last Modified, Invitations, Geofence Configs, Current User — 28 categorías, ~70 herramientas) se eliminó por completo por no ser utilizada por MSPbots.

Los datos de origen de las herramientas conservadas se extrajeron originalmente clonando el repositorio de GitHub de la propia documentación de TSheets (https://github.com/tsheetsteam/api_docs) y analizando cada archivo parcial Markdown/ERB por endpoint (source/includes/APIReference/<Category>/_*.md.erb) para obtener su método HTTP, ruta y tabla de parámetros: el mismo enfoque de extracción estructurada y posterior generación de código utilizado para otros proveedores de API grandes en este programa (ConnectSecure, Dynu, Jira Data Center, Opsgenie). Si más adelante se necesita una categoría eliminada, esa misma fuente puede volver a analizarse de la misma manera.

Autenticación

TSheets utiliza un token de acceso estático obtenido mediante el flujo OAuth/aplicación de API del propio proveedor (consulte el artículo interno de KB de MSPbots enlazado desde su propia configuración de integración). La convención de integración de la propia MSPbots envía este token como Authorization: Bearer <accessToken>, lo que coincide con el formato documentado por la propia TSheets, y este servidor lo reenvía exactamente de esa manera.

Descripción de los parámetros de autorización de la cabecera

Si falta la cabecera, se devuelve 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-TSheets-Access-Token header",
  "required_headers": ["X-TSheets-Access-Token"],
  "optional_headers": []
}

Variables de entorno

Endpoint MCP

• POST /mcp — protocolo MCP (transporte HTTP por streaming)

• GET /health — comprobación de salud, devuelve exactamente {"status": "ok"}. Es una sonda puramente local: no llama a la API de TSheets, por lo que las caídas de TSheets nunca marcan el contenedor como no saludable.

Errores y paginación

• Los errores de las herramientas se devuelven como un envoltorio JSON en banda (no como una excepción lanzada ni un error a nivel de protocolo): {"error": {"code": "...", "message": "...", "retryable": true|false}}. code es uno de not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error, asignado a partir del estado HTTP del upstream.

• Las llamadas salientes a la API de TSheets utilizan un tiempo de espera de conexión de 5 s / lectura de 30 s, reintentan hasta 3 veces con un retroceso exponencial con tope ante 429/5xx (respetando Retry-After) y reutilizan un único grupo de conexiones durante toda la vida del proceso.

• El parámetro limit de cada herramienta retrieve_* tiene un valor predeterminado de 50 y se limita al máximo documentado por página de TSheets de 200 si quien llama solicita más (la propia API de TSheets también tiene un valor predeterminado/máximo de 200, por lo que ambos límites coinciden aquí).

Lista de herramientas

Los nombres de las herramientas son tsheets_<category>_<operation>, derivados del ## Heading de cada operación en la documentación de origen (p. ej., «Retrieve Timesheets» en la categoría timesheets → tsheets_timesheets_retrieve_timesheets). Varios parámetros de filtro de retrieve están documentados como «obligatorios (a menos que se establezca X, Y o Z)»: un requisito de uno-de-N que no puede expresarse claramente como un único parámetro Python estrictamente obligatorio, por lo que se modelan como opcionales y la restricción OR se detalla en el docstring de la propia herramienta. Los parámetros body de los endpoints de crear/actualizar se aceptan como un dict genérico: la propia convención de TSheets los envuelve en {"data": [ {...}, ... ]} (creación/actualización masiva de hasta 50 objetos por llamada), documentado por herramienta.

Ejemplo de prueba

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tsheets_jobcodes_retrieve_jobcodes",
      "arguments": {}
    }
  }'

Verificado en vivo (2026-07-30): un primer token de acceso de prueba resultó estar caducado (401 invalid_grant, confirmado de forma idéntica mediante curl directo — consulte la nota del error más abajo para ver qué detectó esa ejecución). A continuación, se probó un segundo token de acceso recién emitido de extremo a extremo a través de este servidor en ejecución y devolvió datos reales de la cuenta: tsheets_current_user_retrieve_the_current_user devolvió el registro real del usuario actual (nombre, permisos, saldos de PTO) junto con datos complementarios de códigos de trabajo, y tsheets_jobcodes_retrieve_jobcodes (que coincide con uno de los 6 endpoints configurados por el propio MSPbots) devolvió registros reales de códigos de trabajo. Ambos confirman que el flujo completo de solicitud/autenticación/respuesta funciona correctamente contra la API en vivo.

Error corregido durante la autoprueba: el analizador de errores inicial de _raise_for_status suponía que TSheets siempre anida los detalles del error como {"error": {"message": "..."}}, pero TSheets en realidad devuelve un {"error": "invalid_grant", "error_description": "..."} plano, de estilo OAuth, para los fallos de autenticación — llamar a .get() sobre la cadena "invalid_grant" falló con 'str' object has no attribute 'get'. Esto se detectó y corrigió utilizando el primer token de prueba (caducado), antes de que este servidor se considerara terminado.

Referencia de la API

• Descripción general: https://tsheetsteam.github.io/api_docs/

• Código fuente (incl. la colección oficial de Postman): https://github.com/tsheetsteam/api_docs

Limitaciones conocidas

• Reducido de 85 a 15 herramientas el 2026-08-04. La compilación original cubría la API pública completa en 34 categorías según una decisión de alcance anterior. Una decisión de alcance posterior la recortó a exactamente las 6 categorías realmente utilizadas por MSPbots (todas conservadas íntegramente — no fue necesario recortar por categoría, ya que ninguna superaba un puñado de herramientas) — consulte la sección Alcance más arriba para ver la lista completa de las 28 categorías eliminadas (~70 herramientas). Si más adelante se necesita una categoría eliminada, los documentos fuente (https://github.com/tsheetsteam/api_docs) pueden volver a analizarse de la misma manera en que se generaron las herramientas conservadas.

• tsheets_timesheets_delete_timesheets elimina permanentemente los registros de hojas de horas según la propia documentación del proveedor — trátelo como destructivo/irreversible y confírmelo con una persona antes de invocarlo. Las demás herramientas create/update conservadas también modifican datos reales de TSheets (códigos de trabajo, usuarios, campos personalizados).

• Los grupos de filtros "obligatorios" de tipo uno-de-N se modelan como totalmente opcionales — varios endpoints Retrieve documentan un parámetro como "obligatorio (salvo que se establezca X, Y o Z)"; imponer eso como una restricción real no es expresable en una firma de función simple, por lo que todos esos parámetros son opcionales en la firma de la herramienta y el requisito de O se explica en el docstring. Quienes llamen deben proporcionar al menos uno según la restricción documentada o la API en vivo rechazará la solicitud.

• Los parámetros body no están tipados (dict) en lugar de estar completamente modelados — la propia documentación de TSheets muestra variantes de campos según el tipo (p. ej., "Regular Timesheets" frente a "Manual Timesheets" tienen campos obligatorios diferentes dentro del mismo array data), que no se corresponden claramente con parámetros tipados fijos; la propia referencia del proveedor (enlazada más arriba) documenta el esquema exacto por recurso.