harvest-mcp-server

🌾 Servidor MCP de Harvest

No oficial Servidor de Protocolo de Contexto de Modelo (MCP) para integración perfecta con la API de seguimiento de tiempo de Harvest

⚠️ Aviso: Esta es una integración no oficial de terceros con la API de Harvest. Este proyecto no está afiliado, respaldado ni patrocinado por Harvest o Forecast (la empresa detrás de Harvest).

✨ Características

• 🔗 Cobertura completa de la API v2 de Harvest - Más de 40 herramientas que cubren todos los endpoints principales
• 🛡️ Seguridad de tipos - Soporte completo de TypeScript con validación Zod
• ⚡ Alto rendimiento - Construido con async/await y limitación de velocidad adecuada
• 🧪 Probado exhaustivamente - Pruebas unitarias, de integración y de contrato integrales
• 📊 Registro enriquecido - Registro estructurado para depuración y monitoreo
• 🔄 Reintento automático - Lógica de reintento inteligente con retroceso exponencial
• 📖 Compatible con MCP - Funciona con Claude Desktop y otros clientes MCP

🚀 Inicio rápido

Requisitos previos

• Node.js 18+
• Cuenta de Harvest con acceso a la API
• Cliente compatible con MCP (como Claude Desktop)

Instalación

# Install globally
npm install -g @ianaleck/harvest-mcp-server

# Or install locally
npm install @ianaleck/harvest-mcp-server

Configuración

1. Obtén tus credenciales de la API de Harvest:

   • Ve a Harvest → Configuración → Desarrolladores → Tokens de acceso personal
   • Crea un nuevo token
   • Anota tu ID de cuenta (visible en la URL o en la configuración)

2. Configura tu cliente MCP (por ejemplo, Claude Desktop):

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": ["-y", "@ianaleck/harvest-mcp-server"],
      "env": {
        "HARVEST_ACCESS_TOKEN": "your_harvest_personal_access_token",
        "HARVEST_ACCOUNT_ID": "your_harvest_account_id"
      }
    }
  }
}

3. ¡Comienza a usar con Claude!

🎯 Lo que puedes hacer

Una vez conectado, puedes pedirle a Claude que te ayude con:

⏱️ Seguimiento de tiempo

• "Muéstrame todas mis entradas de tiempo de esta semana"
• "Inicia un temporizador para la tarea 'Desarrollo' en el 'Proyecto del sitio web'"
• "¿Cuántas horas trabajé en el Proyecto X el mes pasado?"

📋 Gestión de proyectos

• "Lista todos los proyectos activos del cliente Acme Corp"
• "Crea un nuevo proyecto llamado 'Aplicación móvil' para el cliente TechStart"
• "Muéstrame el presupuesto del proyecto frente al tiempo real invertido"

👥 Gestión de equipo

• "¿Quiénes son todos los usuarios en nuestra cuenta de Harvest?"
• "Muéstrame las entradas de tiempo de Juan de la semana pasada"

💰 Seguimiento financiero

• "Genera un informe de gastos para el cuarto trimestre"
• "Muéstrame todas las facturas impagas"
• "¿Cuál es nuestro total de horas facturables este mes?"

🛠️ Herramientas disponibles

📊 Empresa y cuenta (1 herramienta)

• get_company - Obtener información y configuración de la empresa

⏰ Entradas de tiempo (8 herramientas)

• list_time_entries - Listar entradas de tiempo con filtros
• get_time_entry - Obtener detalles de una entrada de tiempo específica
• create_time_entry - Crear nueva entrada de tiempo
• update_time_entry - Actualizar entrada de tiempo existente
• delete_time_entry - Eliminar entrada de tiempo
• start_timer - Iniciar un temporizador para una tarea
• stop_timer - Detener temporizador en ejecución
• restart_timer - Reiniciar una entrada de tiempo anterior

🏗️ Proyectos (7 herramientas)

• list_projects - Listar todos los proyectos con filtros
• get_project - Obtener detalles de un proyecto específico
• create_project - Crear nuevo proyecto
• update_project - Actualizar detalles del proyecto
• delete_project - Eliminar proyecto
• list_project_task_assignments - Listar asignaciones de tareas para un proyecto
• create_project_task_assignment - Asignar tarea a un proyecto
• update_project_task_assignment - Actualizar asignación de tarea
• delete_project_task_assignment - Eliminar asignación de tarea

📝 Tareas (5 herramientas)

• list_tasks - Listar todas las tareas
• get_task - Obtener detalles de una tarea específica
• create_task - Crear nueva tarea
• update_task - Actualizar detalles de la tarea
• delete_task - Eliminar tarea

🏢 Clientes (5 herramientas)

• list_clients - Listar todos los clientes
• get_client - Obtener detalles de un cliente específico
• create_client - Crear nuevo cliente
• update_client - Actualizar detalles del cliente
• delete_client - Eliminar cliente

👤 Usuarios (6 herramientas)

• list_users - Listar todos los usuarios en la cuenta
• get_user - Obtener detalles de un usuario específico
• get_current_user - Obtener el usuario autenticado actual
• create_user - Crear nuevo usuario
• update_user - Actualizar detalles del usuario
• delete_user - Eliminar usuario

💸 Gastos (6 herramientas)

• list_expenses - Listar gastos con filtros
• get_expense - Obtener detalles de un gasto específico
• create_expense - Crear nuevo gasto
• update_expense - Actualizar detalles del gasto
• delete_expense - Eliminar gasto
• list_expense_categories - Listar todas las categorías de gastos

🧾 Facturas (5 herramientas)

• list_invoices - Listar facturas con filtros
• get_invoice - Obtener detalles de una factura específica
• create_invoice - Crear nueva factura
• update_invoice - Actualizar detalles de la factura
• delete_invoice - Eliminar factura

📋 Presupuestos (5 herramientas)

• list_estimates - Listar presupuestos con filtros
• get_estimate - Obtener detalles de un presupuesto específico
• create_estimate - Crear nuevo presupuesto
• update_estimate - Actualizar detalles del presupuesto
• delete_estimate - Eliminar presupuesto

📈 Informes (4 herramientas)

• get_time_report - Generar informes de tiempo con filtros
• get_expense_report - Generar informes de gastos
• get_project_budget_report - Obtener análisis de presupuesto del proyecto
• get_uninvoiced_report - Obtener tiempo y gastos no facturados

🧪 Desarrollo

Configuración

git clone https://github.com/ianaleck/harvest-mcp-server.git
cd harvest-mcp-server
npm install

Configuración del entorno

cp .env.example .env
# Edit .env with your Harvest API credentials

Pruebas

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:contract

Compilación

# Build for production
npm run build

# Start development server
npm run dev

📋 Requisitos de la API

Este servidor requiere una cuenta de Harvest con acceso a la API. Los usuarios deben cumplir con:

• Términos de servicio de la API de Harvest
• Límites de velocidad de la API de Harvest (100 solicitudes por 15 segundos)

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta nuestras Pautas de contribución para más detalles.

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Realiza tus cambios con pruebas
4. Asegúrate de que todas las pruebas pasen (npm test)
5. Confirma tus cambios (git commit -m 'Add amazing feature')
6. Sube la rama (git push origin feature/amazing-feature)
7. Abre una solicitud de extracción

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

🙏 Agradecimientos

• Harvest por proporcionar una excelente API de seguimiento de tiempo
• Equipo de Protocolo de Contexto de Modelo por la especificación MCP
• Anthropic por Claude y el SDK de MCP

📞 Soporte

• 🐛 Informes de errores: Problemas de GitHub
• 💡 Solicitudes de funciones: Discusiones de GitHub
• 📖 Documentación: Documentación de MCP

---