Harvest MCP Server

Gerencie o controle de tempo, projetos, clientes e tarefas usando a API do Harvest.

Documentação

Harvest MCP Server

Este servidor MCP (Model Context Protocol) fornece integração com a API de controle de tempo e gerenciamento de projetos do Harvest. Ele permite que o Claude e outros assistentes de IA compatíveis com MCP interajam com sua conta do Harvest, ajudando você a gerenciar lançamentos de tempo, projetos, clientes e muito mais.

Recursos

O servidor oferece as seguintes funcionalidades:

Usuários

Listar usuários
Obter detalhes do usuário

Lançamentos de Tempo

Listar lançamentos de tempo com opções de filtro
Criar novos lançamentos de tempo
Iniciar/parar cronômetros
Consultar detalhes de lançamentos de tempo
Obter quadros de horários não enviados (lançamentos de tempo ainda não enviados para aprovação)

Projetos

Listar projetos com opções de filtro (por cliente, is_active, updated_since, page, per_page)
Recuperar informações detalhadas do projeto
Criar novos projetos
Atualizar projetos existentes (também usado para arquivar: passe is_active=False)
Excluir projetos (destrutivo — também exclui os lançamentos de tempo e despesas do projeto, embora as faturas sejam mantidas; arquivar é recomendado em vez disso)

Atribuições de Tarefas

Listar atribuições de tarefas (em toda a conta ou limitadas a um projeto)
Recuperar informações detalhadas de atribuição de tarefas
Criar novas atribuições de tarefas (vincular uma tarefa a um projeto)
Atualizar atribuições de tarefas existentes
Excluir atribuições de tarefas (somente quando não houver lançamentos de tempo registrados contra elas)

Atribuições de Usuários

Listar atribuições de usuários (em toda a conta ou limitadas a um projeto)
Recuperar informações detalhadas de atribuição de usuários
Criar novas atribuições de usuários (vincular um usuário a um projeto)
Atualizar atribuições de usuários existentes
Excluir atribuições de usuários (somente quando não houver lançamentos de tempo ou despesas registrados contra elas)

Clientes

Listar clientes com opções de filtro
Recuperar informações detalhadas do cliente

Tarefas

Listar tarefas disponíveis com opções de filtro

Orçamentos

Listar orçamentos com opções de filtro (por cliente, estado, intervalo de datas, updated_since)
Recuperar informações detalhadas do orçamento
Consultar um orçamento pelo seu número visível ao usuário (ex.: "79")
Listar mensagens associadas a um orçamento
Criar novos orçamentos com itens de linha
Atualizar orçamentos existentes (adicionar/atualizar/excluir itens de linha via _destroy)
Alterar o estado do orçamento (enviar, aceitar, recusar, reabrir) sem enviar e-mail
Enviar mensagens de orçamento (envia o orçamento por e-mail aos destinatários)
Excluir orçamentos

Instruções de Configuração

Pré-requisitos

Python 3.10 ou superior
Conta Harvest com acesso à API
Chave da API Harvest e ID da conta

Integração com o Claude Desktop

Crie ou edite seu arquivo de configuração do Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  - Windows (instalações MSIX — o padrão de claude.ai/download): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
  - Windows (instalações antigas/não-MSIX): %APPDATA%\Claude\claude_desktop_config.json

Adicione a configuração do servidor MCP do Harvest:

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

Reinicie o Claude Desktop.
Verifique a integração procurando o ícone de martelo na interface do Claude.

Exemplos de Consultas

Depois de conectado, você pode perguntar ao Claude sobre seus dados do Harvest com consultas como:

"Mostre meus lançamentos de tempo da semana passada"
"Liste todos os meus projetos ativos"
"Inicie um cronômetro para o projeto [project_id] e a tarefa [task_id]"
"Mostre todos os clientes ativos"
"Liste todas as tarefas disponíveis"
"Obtenha meus quadros de horários não enviados deste mês"
"Mostre lançamentos de tempo não enviados para o usuário [user_id]"
"Mostre todos os orçamentos aceitos deste trimestre"
"Encontre o orçamento numerado [number]"
"Crie um orçamento rascunho para o cliente [client_id] com estes itens de linha..."
"Marque o orçamento [id] como enviado"
"Envie por e-mail o orçamento [id] para client@example.com "
"Crie um novo projeto chamado [name] para o cliente [client_id], cobrado por Projeto, sem orçamento"
"Arquive o projeto [project_id]"
"Atribua a tarefa [task_id] ao projeto [project_id] como faturável"
"Torne o usuário [user_id] gerente de projeto no projeto [project_id]"
"Liste todos os designados ao projeto [project_id]"

Personalização

Você pode modificar o código do servidor para adicionar mais funcionalidades ou personalizar as ferramentas existentes para melhor atender ao seu fluxo de trabalho. O servidor usa FastMCP, o que facilita adicionar novas ferramentas simplesmente adicionando novas funções com o decorador @mcp.tool().

Solução de Problemas

Erros de API: Certifique-se de que sua chave da API Harvest e o ID da conta estejam corretos e tenham as permissões necessárias.
Problemas de Conexão: Verifique se a configuração do Claude Desktop tem o caminho correto para o script do servidor.
Dependências Ausentes: Garanta que você instalou todos os pacotes necessários no seu ambiente Python.

Modo Somente Leitura

Você pode executar o servidor em modo somente leitura definindo a variável de ambiente HARVEST_READ_ONLY para true. Isso desativa todas as operações de escrita (criar lançamentos de tempo, iniciar/parar cronômetros, criar/atualizar/excluir orçamentos, alterar o estado do orçamento, enviar mensagens de orçamento e criar/atualizar/excluir projetos, atribuições de tarefas e atribuições de usuários) enquanto mantém todas as operações de leitura disponíveis.

{
    "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"
            }
        }
    }
}

Quando o modo somente leitura está ativado, qualquer tentativa de chamar uma ferramenta de escrita retornará uma mensagem de erro explicando que o servidor está em modo somente leitura e como habilitar o acesso de escrita.