Peil MCP server
mcp-name: app.peil/peil-mcp
Connect Peil to Claude (or any MCP client): log hours, draft invoices from unbilled hours, add expenses from a receipt, and check where you stand — from a prompt.
- Website: https://peil.app
Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
uvx peil-mcp==0.1.5Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
PEIL_API_KEY=<secret> PEIL_API_URL=<value> claude mcp add app.peil-peil-mcp -- uvx peil-mcp==0.1.5Ejecútalo en una terminal.
{ "mcpServers": { "app.peil-peil-mcp": { "command": "uvx", "args": [ "peil-mcp==0.1.5" ], "env": { "PEIL_API_KEY": "<secret>", "PEIL_API_URL": "<value>" } } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
mcp-name: app.peil/peil-mcp
Connect Peil to Claude (or any MCP client): log hours, draft invoices from unbilled hours, add expenses from a receipt, and check where you stand — from a prompt.
Log hours, draft invoices and check where you stand — finance for Dutch freelancers.
The server is a pure client of Peil's public API. It authenticates with a scoped API key you create in Peil under Settings → Developer. Keys and this server are free on every plan; what is Pro in Peil (emailing invoices, reminders, recurring invoices) stays Pro over a key too.
draft_invoice only ever creates a draft — nothing is sent to your
clients. Sending is a separate tool (send_invoice) that also requires the
separate invoices:send permission on your key. A key without that
permission can never email anything on your behalf.
Reads (read)
Hours (timesheet:write)
Clients (clients:write)
Expenses (expenses:write)
Invoices (invoices:write)
Client-facing email (invoices:send — irreversible, always confirm first)
In Peil: Settings → Developer → create a key with the permissions you want.
Start with read + Log hours + Draft invoices (add Add expenses if you
want your assistant to file receipts); leave Send invoices off unless you
truly want an assistant emailing clients. You'll paste this key into
your assistant's config as PEIL_API_KEY below.
The easy way — no clone, no install:
uvx peil-mcp # runs the latest release on demand
# or, with pipx:
pipx run peil-mcp
→ Your launch command is uvx peil-mcp (or pipx run peil-mcp). Skip to
step 3. Everything below is only needed if you're
running from source (e.g. before the first release, or to hack on it).
You need Python 3.11 or newer and a local copy of this mcp-server/ folder.
Check your Python with python3 --version.
Which method? Run
which uv pipxfirst. If you already haveuv, use A — it's the least work. If not,pipx(B) gives you a clean global command. If you have neither and don't want to install tooling, the plain-venvpath (C) works with nothing but the Python that's already on your machine.
Everywhere below, replace /ABS/PATH/TO/mcp-server with the real absolute path
to this folder (run pwd inside it to get it).
uv (no install step)uv builds and runs on demand — nothing to install first:
uv run --directory /ABS/PATH/TO/mcp-server peil-mcp
→ Your launch command is: uv run --directory /ABS/PATH/TO/mcp-server peil-mcp
Don't have uv? curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux)
or pip install uv.
pipx (isolated global command)pipx installs the server into its own isolated environment and puts a
peil-mcp command on your PATH:
pipx install /ABS/PATH/TO/mcp-server
→ Your launch command is simply: peil-mcp
Don't have pipx? python3 -m pip install --user pipx && python3 -m pipx ensurepath.
venv + pip (works with only stock Python)No extra tooling — just the python3 you already have:
cd /ABS/PATH/TO/mcp-server
python3 -m venv .venv
.venv/bin/pip install .
→ Your launch command is: /ABS/PATH/TO/mcp-server/.venv/bin/peil-mcp
(equivalently /ABS/PATH/TO/mcp-server/.venv/bin/python -m peil_mcp).
Use a plain
pip install .(not-e/editable) for running. An editable install relies on a.pthpath hook that can silently fail to load on some setups, givingModuleNotFoundError: No module named 'peil_mcp'. Editable is only needed if you're modifying the server itself — see Local development.
The only thing that changes between assistants is where the config lives. Every MCP client needs the same three things:
PEIL_API_KEY set to the key from step 1PEIL_API_URL — only if you're pointing at a non-production
Peil (see Local development); defaults to
https://api.peil.app/api/v1.The canonical config block (used by Claude Desktop, Cursor, Windsurf, Cline, and
most others) looks like this — command + args are just your launch command
split on spaces:
{
"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" }
}
}
}
Edit claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\), add the block above, and restart Claude Desktop.
# 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
Anything after -- is the launch command. Verify with claude mcp get peil
(look for Status: ✔ Connected) and use /mcp in a session to reconnect.
Add the canonical block to .cursor/mcp.json (this project) or
~/.cursor/mcp.json (all projects), then enable peil in
Settings → MCP.
Add the canonical block to ~/.codeium/windsurf/mcp_config.json, then hit
Refresh in the Cascade MCP panel.
Open the extension's MCP Servers → Configure panel and add the canonical
block to cline_mcp_settings.json.
VS Code uses a slightly different shape — servers (not mcpServers) and an
explicit type — in .vscode/mcp.json:
{
"servers": {
"peil": {
"type": "stdio",
"command": "peil-mcp",
"args": [],
"env": { "PEIL_API_KEY": "your-key" }
}
}
}
Give it the same command + args + PEIL_API_KEY env. The server speaks MCP
over stdio; if a client can launch a stdio command, it can run Peil.
Once connected, try:
orientation_snapshotlog_hoursdraft_invoicecreate_expenseWith Send invoices left off your key, an assistant can prepare everything but physically cannot email a client — you send from Peil yourself.
Point the server at a local backend with PEIL_API_URL:
PEIL_API_URL=http://localhost:8000/api/v1 PEIL_API_KEY=your-local-key peil-mcp
If you're modifying the server, an editable install picks up your changes without reinstalling:
.venv/bin/pip install -e ".[dev]"
Tests (mocked HTTP, no backend needed — pythonpath = ["src"] in
pyproject.toml makes them independent of the install mechanism):
.venv/bin/pytest
Log hours, draft invoices and check where you stand — finance for Dutch freelancers.
{ "mcpServers": { "app.peil-peil-mcp": { "command": "uvx", "args": [ "peil-mcp==0.1.5" ], "env": { "PEIL_API_KEY": "<secret>", "PEIL_API_URL": "<value>" } } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
El publicador indica estas variables de entorno: PEIL_API_KEY, PEIL_API_URL.
Peil se ejecuta localmente por stdio.
Última comprobación: 2026-11-07. Log hours, draft invoices and check where you stand — finance for Dutch freelancers.