Peil-mcp

Conecte o Peil ao Claude (ou qualquer cliente MCP): registre horas, faça rascunhos de faturas a partir de horas não faturadas e obtenha insights financeiros na sua prática freelance. Tudo em linguagem natural.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Peil

mcp-name: app.peil/peil-mcp

Conecte o Peil ao Claude (ou a qualquer cliente MCP): registre horas, crie rascunhos de faturas a partir de horas não faturadas e verifique sua situação — a partir de um prompt.

Site: https://peil.app
Documentação: https://peil.app/en/docs/mcp
Código-fonte: https://github.com/Luminc/peil-mcp

O servidor é um cliente puro da API pública do Peil. Ele autentica com uma chave de API com escopo que você cria no Peil em Configurações → Desenvolvedor (Pro).

Rascunho por padrão

draft_invoice apenas cria um rascunho — nada é enviado aos seus clientes. O envio é uma ferramenta separada (send_invoice) que também exige a permissão separada invoices:send na sua chave. Uma chave sem essa permissão nunca poderá enviar e-mails em seu nome.

Ferramentas

Leituras (read)

Ferramenta	O que faz
`list_clients`	Lista seus clientes
`get_client_details`	Detalhes de um cliente, incluindo se uma tarifa padrão está definida
`list_unbilled`	Horas não faturadas por cliente em um período
`list_invoices`	Lista faturas, filtráveis por status / cliente
`orientation_snapshot`	Posição de pendências / vencidas / rascunhos / acumulado no ano
`get_reminder_copy`	Seu texto de e-mail de lembrete personalizado + agendamento

Horas (timesheet:write)

Ferramenta	O que faz
`log_hours`	Adiciona um lançamento de horas (tarifa padrão do cliente, salvo se informada)
`edit_hours`	Edita um lançamento (apenas os campos que você passar são alterados)
`delete_hours`	Exclui um lançamento (bloqueado se estiver em uma fatura enviada/paga)

Clientes (clients:write)

Ferramenta	O que faz
`create_client` / `update_client` / `delete_client`	CRUD de clientes (exclusão bloqueada se houver projetos/faturas enviadas)

Faturas (invoices:write)

Ferramenta	O que faz
`draft_invoice`	Cria rascunho de fatura a partir de horas não faturadas (resumo / por_projeto / por_dia)
`set_invoice_status`	Altera o status (ex.: marcar como paga) — não envia e-mail a ninguém
`update_invoice`	Edita campos seguros (data de vencimento, data de pagamento, observações)
`delete_invoice` / `archive_invoice`	Excluir (pagas são bloqueadas) / arquivar
`set_reminder_copy`	Escreve texto de e-mail de lembrete personalizado para um tom/idioma

E-mail para o cliente (invoices:send — irreversível, sempre confirme antes)

Ferramenta	O que faz
`send_invoice`	Envia uma fatura por e-mail ao cliente agora
`schedule_send`	Agenda um rascunho para envio por e-mail em um horário futuro
`cancel_scheduled_send`	Cancela um envio agendado
`send_reminder`	Envia um lembrete de pagamento para uma fatura enviada/vencida

1. Crie sua chave

No Peil: Configurações → Desenvolvedor → crie uma chave com as permissões desejadas. Comece com leitura + Registrar horas + Criar rascunho de faturas; deixe Enviar faturas desativado a menos que você realmente queira que um assistente envie e-mails aos clientes. Você colará essa chave na configuração do seu assistente como PEIL_API_KEY abaixo.

2. Instale o servidor

O jeito fácil — sem clone, sem instalação (assim que peil-mcp for publicado no PyPI):

uvx peil-mcp          # runs the latest release on demand
# or, with pipx:
pipx run peil-mcp

→ Seu comando de inicialização é uvx peil-mcp (ou pipx run peil-mcp). Pule para passo 3. Tudo abaixo só é necessário se você estiver executando a partir do código-fonte (ex.: antes do primeiro lançamento, ou para modificar).

A partir do código-fonte

Você precisa de Python 3.11 ou mais recente e uma cópia local desta pasta mcp-server/. Verifique seu Python com python3 --version.

Qual método? Execute which uv pipx primeiro. Se você já tiver uv, use A — é o que dá menos trabalho. Se não, pipx (B) oferece um comando global limpo. Se você não tiver nenhum dos dois e não quiser instalar ferramentas, o caminho com venv puro (C) funciona apenas com o Python que já está na sua máquina.

Em todos os casos abaixo, substitua /ABS/PATH/TO/mcp-server pelo caminho absoluto real até esta pasta (execute pwd dentro dela para obtê-lo).

A. Com `uv` (sem etapa de instalação)

uv compila e executa sob demanda — nada para instalar antes:

uv run --directory /ABS/PATH/TO/mcp-server peil-mcp

→ Seu comando de inicialização é: uv run --directory /ABS/PATH/TO/mcp-server peil-mcp

Não tem uv? curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) ou pip install uv.

B. Com `pipx` (comando global isolado)

pipx instala o servidor em seu próprio ambiente isolado e coloca um comando peil-mcp no seu PATH:

pipx install /ABS/PATH/TO/mcp-server

→ Seu comando de inicialização é simplesmente: peil-mcp

Não tem pipx? python3 -m pip install --user pipx && python3 -m pipx ensurepath.

C. `venv` puro + `pip` (funciona apenas com Python padrão)

Sem ferramentas extras — apenas o python3 que você já tem:

cd /ABS/PATH/TO/mcp-server
python3 -m venv .venv
.venv/bin/pip install .

→ Seu comando de inicialização é: /ABS/PATH/TO/mcp-server/.venv/bin/peil-mcp (equivalentemente /ABS/PATH/TO/mcp-server/.venv/bin/python -m peil_mcp).

Use um pip install . comum (não -e/editável) para execução. Uma instalação editável depende de um hook de caminho .pth que pode falhar silenciosamente ao carregar em algumas configurações, resultando em ModuleNotFoundError: No module named 'peil_mcp'. Editável só é necessário se você estiver modificando o próprio servidor — veja Desenvolvimento local.

3. Conecte seu assistente

A única coisa que muda entre assistentes é onde a configuração fica. Todo cliente MCP precisa das mesmas três coisas:

comando — seu comando de inicialização do passo 2
env — PEIL_API_KEY definido com a chave do passo 1
(opcional) PEIL_API_URL — apenas se você estiver apontando para um Peil que não seja de produção (veja Desenvolvimento local); o padrão é https://api.peil.app/api/v1.

O bloco de configuração canônico (usado pelo Claude Desktop, Cursor, Windsurf, Cline e a maioria dos outros) tem esta aparência — command + args são apenas seu comando de inicialização dividido por espaços:

{
  "mcpServers": {
    "peil": {
      "command": "peil-mcp",          // or "uv", or the venv's python path
      "args": [],                     // e.g. ["run","--directory","/ABS/PATH/TO/mcp-server","peil-mcp"] for uv
      "env": { "PEIL_API_KEY": "your-key" }
    }
  }
}

Claude Desktop

Edite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), adicione o bloco acima e reinicie o Claude Desktop.

Claude Code (CLI)

# pipx / venv (single-command launcher):
claude mcp add peil -e PEIL_API_KEY=your-key -- peil-mcp

# uv:
claude mcp add peil -e PEIL_API_KEY=your-key -- uv run --directory /ABS/PATH/TO/mcp-server peil-mcp

Qualquer coisa após -- é o comando de inicialização. Verifique com claude mcp get peil (procure por Status: ✔ Connected) e use /mcp em uma sessão para reconectar.

Cursor

Adicione o bloco canônico a .cursor/mcp.json (este projeto) ou ~/.cursor/mcp.json (todos os projetos) e ative peil em Configurações → MCP.

Windsurf

Adicione o bloco canônico a ~/.codeium/windsurf/mcp_config.json e clique em Atualizar no painel MCP do Cascade.

Cline / Roo (VS Code)

Abra o painel Servidores MCP → Configurar da extensão e adicione o bloco canônico a cline_mcp_settings.json.

VS Code (modo agente nativo do Copilot)

O VS Code usa um formato ligeiramente diferente — servers (não mcpServers) e um type explícito — em .vscode/mcp.json:

{
  "servers": {
    "peil": {
      "type": "stdio",
      "command": "peil-mcp",
      "args": [],
      "env": { "PEIL_API_KEY": "your-key" }
    }
  }
}

Qualquer outro cliente MCP

Forneça o mesmo comando + args + env PEIL_API_KEY. O servidor fala MCP via stdio; se um cliente puder iniciar um comando stdio, ele poderá executar o Peil.

Primeiros prompts

Depois de conectado, experimente:

"Como está minha situação?" → orientation_snapshot
"Registre 6 horas para De Correspondent hoje para trabalho de edição." → log_hours
"Crie um rascunho de fatura a partir das minhas horas não faturadas para De Correspondent." → draft_invoice

Com Enviar faturas desativado na sua chave, um assistente pode preparar tudo, mas fisicamente não pode enviar e-mails a um cliente — você envia pelo próprio Peil.

Desenvolvimento local

Aponte o servidor para um backend local com PEIL_API_URL:

PEIL_API_URL=http://localhost:8000/api/v1 PEIL_API_KEY=your-local-key peil-mcp

Se você estiver modificando o servidor, uma instalação editável capta suas alterações sem reinstalar:

.venv/bin/pip install -e ".[dev]"

Testes (HTTP simulado, sem necessidade de backend — pythonpath = ["src"] em pyproject.toml os torna independentes do mecanismo de instalação):

.venv/bin/pytest