harvest-mcp-server

Integração de rastreamento de tempo do Harvest com mais de 40 ferramentas para gerenciar entradas de tempo, projetos, clientes, tarefas e gerar relatórios de tempo via API v2 do Harvest

GitHub
8

Documentação

🌾 Harvest MCP Server

npm version TypeScript MCP License: MIT Tests Buy Me A Coffee

Não oficial Servidor Model Context Protocol (MCP) para integração perfeita com a API de controle de tempo Harvest

⚠️ Aviso: Esta é uma integração não oficial, de terceiros, com a API Harvest. Este projeto não é afiliado, endossado ou patrocinado pela Harvest ou Forecast (a empresa por trás da Harvest).

harvest-mcp-server MCP server

✨ Recursos

  • 🔗 Cobertura Completa da Harvest API v2 - Mais de 40 ferramentas cobrindo todos os endpoints principais
  • 🛡️ Type-Safe - Suporte completo a TypeScript com validação Zod
  • ⚡ Alto Desempenho - Construído com async/await e limitação de taxa adequada
  • 🧪 Totalmente Testado - Testes abrangentes de unidade, integração e contrato
  • 📊 Logging Rico - Logging estruturado para depuração e monitoramento
  • 🔄 Repetição Automática - Lógica de repetição inteligente com backoff exponencial
  • 📖 Compatível com MCP - Funciona com Claude Desktop e outros clientes MCP

🚀 Início Rápido

Pré-requisitos

  • Node.js 18+
  • Conta Harvest com acesso à API
  • Cliente compatível com MCP (como Claude Desktop)

Instalação

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

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

Configuração

  1. Obtenha suas credenciais da API Harvest:

    • Vá para Harvest → Configurações → Desenvolvedores → Tokens de Acesso Pessoal
    • Crie um novo token
    • Anote seu ID de Conta (visível na URL ou nas configurações)

  2. Configure seu cliente MCP (ex.: 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"
      }
    }
  }
}
  1. Comece a usar com o Claude!

🎯 O Que Você Pode Fazer

Uma vez conectado, você pode pedir ao Claude para ajudar com:

⏱️ Controle de Tempo

  • "Mostre-me todos os meus registros de tempo desta semana"
  • "Inicie um cronômetro para a tarefa 'Desenvolvimento' no 'Projeto Website'"
  • "Quantas horas trabalhei no Projeto X no mês passado?"

📋 Gerenciamento de Projetos

  • "Liste todos os projetos ativos para o cliente Acme Corp"
  • "Crie um novo projeto chamado 'Aplicativo Mobile' para o cliente TechStart"
  • "Mostre-me o orçamento do projeto versus o tempo real gasto"

👥 Gerenciamento de Equipe

  • "Quem são todos os usuários na nossa conta Harvest?"
  • "Mostre-me os registros de tempo do João da semana passada"

💰 Acompanhamento Financeiro

  • "Gere um relatório de despesas para o Q4"
  • "Mostre-me todas as faturas não pagas"
  • "Qual é o total de horas faturáveis deste mês?"

🛠️ Ferramentas Disponíveis

📊 Empresa & Conta (1 ferramenta)
  • get_company - Obter informações e configurações da empresa
⏰ Registros de Tempo (8 ferramentas)
  • list_time_entries - Listar registros de tempo com filtros
  • get_time_entry - Obter detalhes de um registro de tempo específico
  • create_time_entry - Criar novo registro de tempo
  • update_time_entry - Atualizar registro de tempo existente
  • delete_time_entry - Excluir registro de tempo
  • start_timer - Iniciar um cronômetro para uma tarefa
  • stop_timer - Parar cronômetro em execução
  • restart_timer - Reiniciar um registro de tempo anterior
🏗️ Projetos (7 ferramentas)
  • list_projects - Listar todos os projetos com filtros
  • get_project - Obter detalhes de um projeto específico
  • create_project - Criar novo projeto
  • update_project - Atualizar detalhes do projeto
  • delete_project - Excluir projeto
  • list_project_task_assignments - Listar atribuições de tarefas para o projeto
  • create_project_task_assignment - Atribuir tarefa ao projeto
  • update_project_task_assignment - Atualizar atribuição de tarefa
  • delete_project_task_assignment - Remover atribuição de tarefa
📝 Tarefas (5 ferramentas)
  • list_tasks - Listar todas as tarefas
  • get_task - Obter detalhes de uma tarefa específica
  • create_task - Criar nova tarefa
  • update_task - Atualizar detalhes da tarefa
  • delete_task - Excluir tarefa
🏢 Clientes (5 ferramentas)
  • list_clients - Listar todos os clientes
  • get_client - Obter detalhes de um cliente específico
  • create_client - Criar novo cliente
  • update_client - Atualizar detalhes do cliente
  • delete_client - Excluir cliente
👤 Usuários (6 ferramentas)
  • list_users - Listar todos os usuários na conta
  • get_user - Obter detalhes de um usuário específico
  • get_current_user - Obter usuário autenticado atual
  • create_user - Criar novo usuário
  • update_user - Atualizar detalhes do usuário
  • delete_user - Excluir usuário
💸 Despesas (6 ferramentas)
  • list_expenses - Listar despesas com filtros
  • get_expense - Obter detalhes de uma despesa específica
  • create_expense - Criar nova despesa
  • update_expense - Atualizar detalhes da despesa
  • delete_expense - Excluir despesa
  • list_expense_categories - Listar todas as categorias de despesas
🧾 Faturas (5 ferramentas)
  • list_invoices - Listar faturas com filtros
  • get_invoice - Obter detalhes de uma fatura específica
  • create_invoice - Criar nova fatura
  • update_invoice - Atualizar detalhes da fatura
  • delete_invoice - Excluir fatura
📋 Orçamentos (5 ferramentas)
  • list_estimates - Listar orçamentos com filtros
  • get_estimate - Obter detalhes de um orçamento específico
  • create_estimate - Criar novo orçamento
  • update_estimate - Atualizar detalhes do orçamento
  • delete_estimate - Excluir orçamento
📈 Relatórios (4 ferramentas)
  • get_time_report - Gerar relatórios de tempo com filtros
  • get_expense_report - Gerar relatórios de despesas
  • get_project_budget_report - Obter análise de orçamento do projeto
  • get_uninvoiced_report - Obter tempo e despesas não faturados

🧪 Desenvolvimento

Configuração

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

Configuração de Ambiente

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

Testes

# 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

Build

# Build for production
npm run build

# Start development server
npm run dev

📋 Requisitos da API

Este servidor requer uma conta Harvest com acesso à API. Os usuários devem cumprir:

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes.

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça suas alterações com testes
  4. Garanta que todos os testes passem (npm test)
  5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  6. Envie para o branch (git push origin feature/amazing-feature)
  7. Abra um Pull Request

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

📞 Suporte

Feito com ❤️ para a comunidade MCP

⭐ Marque este projeto com estrela se você o achar útil!