Harvest MCP Server

Gestionar el seguimiento del tiempo, proyectos, clientes y tareas usando la API de Harvest.

GitHub
37
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Harvest MCP Server

Este servidor MCP (Model Context Protocol) proporciona integración con la API de seguimiento de tiempo y gestión de proyectos de Harvest. Permite que Claude y otros asistentes de IA compatibles con MCP interactúen con tu cuenta de Harvest, ayudándote a gestionar entradas de tiempo, proyectos, clientes y más.

Características

El servidor proporciona la siguiente funcionalidad:

Usuarios

  • Listar usuarios
  • Obtener detalles de usuario

Entradas de Tiempo

  • Listar entradas de tiempo con opciones de filtrado
  • Crear nuevas entradas de tiempo
  • Iniciar/detener temporizadores
  • Consultar detalles de entradas de tiempo
  • Obtener hojas de tiempo no enviadas (entradas de tiempo aún no enviadas para aprobación)

Proyectos

  • Listar proyectos con opciones de filtrado (por cliente, is_active, updated_since, page, per_page)
  • Recuperar información detallada del proyecto
  • Crear nuevos proyectos
  • Actualizar proyectos existentes (también se usa para archivar: pasar is_active=False)
  • Eliminar proyectos (destructivo — también elimina las entradas de tiempo y gastos del proyecto, aunque las facturas se conservan; se recomienda archivar en su lugar)

Asignaciones de Tareas

  • Listar asignaciones de tareas (a nivel de cuenta o limitadas a un proyecto)
  • Recuperar información detallada de asignación de tareas
  • Crear nuevas asignaciones de tareas (vincular una tarea a un proyecto)
  • Actualizar asignaciones de tareas existentes
  • Eliminar asignaciones de tareas (solo cuando no hay entradas de tiempo registradas contra ellas)

Asignaciones de Usuarios

  • Listar asignaciones de usuarios (a nivel de cuenta o limitadas a un proyecto)
  • Recuperar información detallada de asignación de usuarios
  • Crear nuevas asignaciones de usuarios (vincular un usuario a un proyecto)
  • Actualizar asignaciones de usuarios existentes
  • Eliminar asignaciones de usuarios (solo cuando no hay entradas de tiempo o gastos registrados contra ellas)

Clientes

  • Listar clientes con opciones de filtrado
  • Recuperar información detallada del cliente

Tareas

  • Listar tareas disponibles con opciones de filtrado

Presupuestos

  • Listar presupuestos con opciones de filtrado (por cliente, estado, rango de fechas, updated_since)
  • Recuperar información detallada del presupuesto
  • Buscar un presupuesto por su número visible para el usuario (ej. "79")
  • Listar mensajes asociados con un presupuesto
  • Crear nuevos presupuestos con partidas
  • Actualizar presupuestos existentes (añadir/actualizar/eliminar partidas mediante _destroy)
  • Cambiar el estado del presupuesto (enviar, aceptar, rechazar, reabrir) sin enviar correo electrónico
  • Enviar mensajes de presupuesto (envía el presupuesto por correo electrónico a los destinatarios)
  • Eliminar presupuestos

Instrucciones de Configuración

Requisitos Previos

  • Python 3.10 o superior
  • Cuenta de Harvest con acceso a la API
  • Clave de API de Harvest e ID de cuenta

Integración con Claude Desktop

  1. Crea o edita tu archivo de configuración de Claude Desktop:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows (instalaciones MSIX — el predeterminado desde claude.ai/download): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
    • Windows (instalaciones antiguas/no MSIX): %APPDATA%\Claude\claude_desktop_config.json
  2. Añade la configuración del servidor Harvest MCP:
    {
    "mcpServers": {
    "harvest": {
    "command": "uv",
    "args": [
    "run",
    "--directory",
    "change_directory",
    "harvest-mcp-server.py"
    ],
    "env": {
    "HARVEST_ACCOUNT_ID": "account_id",
    "HARVEST_API_KEY": "api_key"
    }
    }
    }
    }
  3. Reinicia Claude Desktop.
  4. Verifica la integración buscando el icono de martillo en la interfaz de Claude.

Consultas de Ejemplo

Una vez conectado, puedes preguntar a Claude sobre tus datos de Harvest con consultas como:

  • "Muéstrame mis entradas de tiempo de la semana pasada"
  • "Lista todos mis proyectos activos"
  • "Inicia un temporizador para el proyecto [project_id] y la tarea [task_id]"
  • "Muéstrame todos los clientes activos"
  • "Lista todas las tareas disponibles"
  • "Obtén mis hojas de tiempo no enviadas de este mes"
  • "Muéstrame entradas de tiempo no enviadas para el usuario [user_id]"
  • "Muéstrame todos los presupuestos aceptados de este trimestre"
  • "Encuentra el presupuesto numerado [number]"
  • "Crea un presupuesto borrador para el cliente [client_id] con estas partidas..."
  • "Marca el presupuesto [id] como enviado"
  • "Envía por correo electrónico el presupuesto [id] a client@example.com"
  • "Crea un nuevo proyecto llamado [name] para el cliente [client_id], facturado por Proyecto, sin presupuesto"
  • "Archiva el proyecto [project_id]"
  • "Asigna la tarea [task_id] al proyecto [project_id] como facturable"
  • "Haz que el usuario [user_id] sea gestor de proyectos en el proyecto [project_id]"
  • "Lista a todos los asignados al proyecto [project_id]"

Personalización

Puedes modificar el código del servidor para añadir más funcionalidad o personalizar las herramientas existentes para adaptarlas mejor a tu flujo de trabajo. El servidor utiliza FastMCP, lo que facilita añadir nuevas herramientas simplemente agregando nuevas funciones con el decorador @mcp.tool().

Solución de Problemas

  • Errores de API: Asegúrate de que tu clave de API de Harvest y tu ID de cuenta sean correctos y tengan los permisos necesarios.
  • Problemas de Conexión: Verifica que tu configuración de Claude Desktop tenga la ruta correcta al script del servidor.
  • Dependencias Faltantes: Asegúrate de haber instalado todos los paquetes requeridos en tu entorno de Python.

Modo de Solo Lectura

Puedes ejecutar el servidor en modo de solo lectura estableciendo la variable de entorno HARVEST_READ_ONLY a true. Esto desactiva todas las operaciones de escritura (crear entradas de tiempo, iniciar/detener temporizadores, crear/actualizar/eliminar presupuestos, cambiar el estado de presupuestos, enviar mensajes de presupuestos, y crear/actualizar/eliminar proyectos, asignaciones de tareas y asignaciones de usuarios) mientras mantiene disponibles todas las operaciones de lectura.

{ "mcpServers": { "harvest": { "command": "uv", "args": [ "run", "--directory", "change_directory", "harvest-mcp-server.py" ], "env": { "HARVEST_ACCOUNT_ID": "account_id", "HARVEST_API_KEY": "api_key", "HARVEST_READ_ONLY": "true" } } } }

Cuando el modo de solo lectura está habilitado, cualquier intento de llamar a una herramienta de escritura devolverá un mensaje de error explicando que el servidor está en modo de solo lectura y cómo habilitar el acceso de escritura.

Notas de Seguridad

Este servidor requiere tus credenciales de API de Harvest para funcionar. Asegúrate de:

  • Mantener tu clave de API segura
  • No compartir tu archivo claude_desktop_config.json
  • Considerar usar una clave de API dedicada con permisos limitados para esta integración