Peil-mcp

Servidor MCP de Peil

mcp-name: app.peil/peil-mcp

Conecta Peil a Claude (o cualquier cliente MCP): registra horas, redacta facturas a partir de horas no facturadas y comprueba tu situación — desde un prompt.

• Sitio web: https://peil.app
• Documentación: https://peil.app/en/docs/mcp
• Código fuente: https://github.com/Luminc/peil-mcp

El servidor es un cliente puro de la API pública de Peil. Se autentica con una clave de API con alcance que creas en Peil en Configuración → Desarrollador (Pro).

Borrador por defecto

draft_invoice solo crea un borrador — no se envía nada a tus clientes. El envío es una herramienta separada (send_invoice) que también requiere el permiso separado invoices:send en tu clave. Una clave sin ese permiso nunca puede enviar correos electrónicos en tu nombre.

Herramientas

Lecturas (read)

Herramienta	Qué hace
list_clients	Lista tus clientes
get_client_details	Detalles de un cliente, incl. si se ha establecido una tarifa predeterminada
list_unbilled	Horas no facturadas por cliente para un período
list_invoices	Lista facturas, filtrables por estado / cliente
orientation_snapshot	Posición de pendientes / vencidas / borradores / YTD
get_reminder_copy	Tu texto de correo de recordatorio personalizado + programación

Horas (timesheet:write)

Herramienta	Qué hace
log_hours	Añade una entrada de hoja de horas (tarifa predeterminada del cliente a menos que se indique)
edit_hours	Edita una entrada (solo cambian los campos que pasas)
delete_hours	Elimina una entrada (bloqueado si está en una factura enviada/pagada)

Clientes (clients:write)

Herramienta	Qué hace
create_client / update_client / delete_client	CRUD de clientes (eliminación bloqueada si tiene proyectos/facturas enviadas)

Facturas (invoices:write)

Herramienta	Qué hace
draft_invoice	Redacta una factura a partir de horas no facturadas (resumen / por_proyecto / por_día)
set_invoice_status	Cambia el estado (p. ej., marcar como pagada) — no envía correos a nadie
update_invoice	Edita campos seguros (fecha de vencimiento, fecha de pago, notas)
delete_invoice / archive_invoice	Eliminar (las pagadas bloqueadas) / archivar
set_reminder_copy	Escribe texto de correo de recordatorio personalizado para un tono/idioma

Correo electrónico al cliente (invoices:send — irreversible, confirma siempre primero)

Herramienta	Qué hace
send_invoice	Envía una factura al cliente ahora
schedule_send	Programa un borrador para enviarlo por correo en un momento futuro
cancel_scheduled_send	Cancela un envío programado
send_reminder	Envía un recordatorio de pago para una factura enviada/vencida

---

1. Crea tu clave

En Peil: Configuración → Desarrollador → crea una clave con los permisos que quieras. Empieza con lectura + Registrar horas + Redactar facturas; deja Enviar facturas desactivado a menos que realmente quieras que un asistente envíe correos a los clientes. Pegarás esta clave en la configuración de tu asistente como PEIL_API_KEY a continuación.

2. Instala el servidor

La forma fácil — sin clonar, sin instalar (una vez que peil-mcp se publique en PyPI):

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

→ Tu comando de lanzamiento es uvx peil-mcp (o pipx run peil-mcp). Salta al paso 3. Todo lo siguiente solo es necesario si estás ejecutando desde el código fuente (p. ej., antes de la primera versión, o para modificarlo).

Desde el código fuente

Necesitas Python 3.11 o superior y una copia local de esta carpeta mcp-server/. Comprueba tu Python con python3 --version.

¿Qué método? Ejecuta which uv pipx primero. Si ya tienes uv, usa A — es el que menos trabajo requiere. Si no, pipx (B) te da un comando global limpio. Si no tienes ninguno y no quieres instalar herramientas, la ruta simple de venv (C) funciona solo con el Python que ya tienes en tu máquina.

En todo lo siguiente, reemplaza /ABS/PATH/TO/mcp-server con la ruta absoluta real a esta carpeta (ejecuta pwd dentro de ella para obtenerla).

A. Con uv (sin paso de instalación)

uv compila y ejecuta bajo demanda — no hay nada que instalar primero:

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

→ Tu comando de lanzamiento es: uv run --directory /ABS/PATH/TO/mcp-server peil-mcp

¿No tienes uv? curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) o pip install uv.

B. Con pipx (comando global aislado)

pipx instala el servidor en su propio entorno aislado y coloca un comando peil-mcp en tu PATH:

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

→ Tu comando de lanzamiento es simplemente: peil-mcp

¿No tienes pipx? python3 -m pip install --user pipx && python3 -m pipx ensurepath.

C. venv simple + pip (funciona solo con Python estándar)

Sin herramientas adicionales — solo el python3 que ya tienes:

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

→ Tu comando de lanzamiento es: /ABS/PATH/TO/mcp-server/.venv/bin/peil-mcp (equivalentemente /ABS/PATH/TO/mcp-server/.venv/bin/python -m peil_mcp).

Usa un pip install . simple (no -e/editable) para ejecutar. Una instalación editable depende de un enlace de ruta .pth que puede fallar silenciosamente al cargar en algunas configuraciones, dando ModuleNotFoundError: No module named 'peil_mcp'. Editable solo es necesario si estás modificando el servidor en sí — consulta Desarrollo local.

3. Conecta tu asistente

Lo único que cambia entre asistentes es dónde vive la configuración. Cada cliente MCP necesita las mismas tres cosas:

• comando — tu comando de lanzamiento del paso 2
• env — PEIL_API_KEY configurado con la clave del paso 1
• (opcional) PEIL_API_URL — solo si apuntas a un Peil que no sea de producción (consulta Desarrollo local); por defecto es https://api.peil.app/api/v1.

El bloque de configuración canónico (usado por Claude Desktop, Cursor, Windsurf, Cline y la mayoría de los demás) se ve así — command + args son solo tu comando de lanzamiento dividido en espacios:

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

Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), añade el bloque anterior y reinicia 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

Todo lo que esté después de -- es el comando de lanzamiento. Verifica con claude mcp get peil (busca Status: ✔ Connected) y usa /mcp en una sesión para reconectar.

Cursor

Añade el bloque canónico a .cursor/mcp.json (este proyecto) o ~/.cursor/mcp.json (todos los proyectos), luego habilita peil en Configuración → MCP.

Windsurf

Añade el bloque canónico a ~/.codeium/windsurf/mcp_config.json, luego pulsa Actualizar en el panel Cascade MCP.

Cline / Roo (VS Code)

Abre el panel Servidores MCP → Configurar de la extensión y añade el bloque canónico a cline_mcp_settings.json.

VS Code (modo agente nativo de Copilot)

VS Code usa una forma ligeramente diferente — servers (no mcpServers) y un type explícito — en .vscode/mcp.json:

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

Cualquier otro cliente MCP

Dale el mismo comando + args + entorno PEIL_API_KEY. El servidor habla MCP sobre stdio; si un cliente puede lanzar un comando stdio, puede ejecutar Peil.

Primeros prompts

Una vez conectado, prueba:

• "¿Dónde estoy?" → orientation_snapshot
• "Registra 6 horas para De Correspondent hoy por trabajo de edición." → log_hours
• "Redacta una factura a partir de mis horas no facturadas para De Correspondent." → draft_invoice

Con Enviar facturas desactivado en tu clave, un asistente puede preparar todo, pero físicamente no puede enviar correos a un cliente — tú envías desde Peil mismo.

---

Desarrollo local

Apunta el servidor a un backend local con PEIL_API_URL:

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

Si estás modificando el servidor, una instalación editable recoge tus cambios sin reinstalar:

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

Pruebas (HTTP simulado, sin necesidad de backend — pythonpath = ["src"] en pyproject.toml las hace independientes del mecanismo de instalación):

.venv/bin/pytest