How do I install Peil?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Peil need an API key?

The publisher lists these environment variables: PEIL_API_KEY, PEIL_API_URL.

When was Peil last checked?

Last checked 2026-11-07. Log hours, draft invoices and check where you stand — finance for Dutch freelancers.

Peil MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx peil-mcp==0.1.5

Credentials from the publisher

PEIL_API_KEY — Scoped API key from Peil under Settings -> Developer settings.
PEIL_API_URL — Override the API base URL. Defaults to https://api.peil.app/api/v1.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1PEIL_API_KEY=<secret> PEIL_API_URL=<value> claude mcp add app.peil-peil-mcp -- uvx peil-mcp==0.1.5

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "app.peil-peil-mcp": {4      "command": "uvx",5      "args": [6        "peil-mcp==0.1.5"7      ],8      "env": {9        "PEIL_API_KEY": "<secret>",10        "PEIL_API_URL": "<value>"11      }12    }13  }14}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

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.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.5
API key

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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
Docs: https://peil.app/en/docs/mcp
Source: https://github.com/Luminc/peil-mcp

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-by-default

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.

Tools

Reads (read)

Tool	What it does
`list_clients`	List your clients
`get_client_details`	One client's details, incl. whether a default rate is set
`list_unbilled`	Unbilled hours per client for a period
`list_invoices`	List invoices, filterable by status / client
`orientation_snapshot`	Outstanding / overdue / drafts / YTD position
`get_reminder_copy`	Your custom reminder email copy + schedule
`list_expenses`	A year's one-off expenses, and which have no receipt kept

Hours (timesheet:write)

Tool	What it does
`log_hours`	Add a timesheet entry (client default rate unless given)
`edit_hours`	Edit an entry (only the fields you pass change)
`delete_hours`	Delete an entry (blocked if on a sent/paid invoice)

Clients (clients:write)

Tool	What it does
`create_client` / `update_client` / `delete_client`	Client CRUD (delete blocked if it has projects/sent invoices)

Expenses (expenses:write)

Tool	What it does
`create_expense`	Add an expense as the receipt says it: total, Dutch btw, category (key or label). Your assistant can read the receipt; the photo itself is kept in the Peil app

Invoices (invoices:write)

Tool	What it does
`draft_invoice`	Draft an invoice from unbilled hours (summary / by_project / per_day)
`set_invoice_status`	Change status (e.g. mark paid) — does not email anyone
`update_invoice`	Edit safe fields (due date, payment date, notes)
`delete_invoice` / `archive_invoice`	Delete (paid ones blocked) / archive
`set_reminder_copy`	Write custom reminder email copy for one tone/language

Client-facing email (invoices:send — irreversible, always confirm first)

Tool	What it does
`send_invoice`	Email an invoice to the client now
`schedule_send`	Schedule a draft to be emailed at a future time
`cancel_scheduled_send`	Cancel a scheduled send
`send_reminder`	Email a payment reminder for a sent/overdue invoice

1. Create your key

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.

2. Install the server

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).

From source

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 pipx first. If you already have uv, 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-venv path (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).

A. With `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.

B. With `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.

C. Plain `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 .pth path hook that can silently fail to load on some setups, giving ModuleNotFoundError: No module named 'peil_mcp'. Editable is only needed if you're modifying the server itself — see Local development.

3. Connect your assistant

The only thing that changes between assistants is where the config lives. Every MCP client needs the same three things:

command — your launch command from step 2
env — PEIL_API_KEY set to the key from step 1
(optional) PEIL_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" }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), add the block above, and restart 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

Anything after -- is the launch command. Verify with claude mcp get peil (look for Status: ✔ Connected) and use /mcp in a session to reconnect.

Cursor

Add the canonical block to .cursor/mcp.json (this project) or ~/.cursor/mcp.json (all projects), then enable peil in Settings → MCP.

Windsurf

Add the canonical block to ~/.codeium/windsurf/mcp_config.json, then hit Refresh in the Cascade MCP panel.

Cline / Roo (VS Code)

Open the extension's MCP Servers → Configure panel and add the canonical block to cline_mcp_settings.json.

VS Code (native Copilot agent mode)

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

Any other MCP client

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.

First prompts

Once connected, try:

"Where do I stand?" → orientation_snapshot
"Log 6 hours to De Correspondent today for editing work." → log_hours
"Draft an invoice from my unbilled hours for De Correspondent." → draft_invoice
"Here's my train ticket, add it as an expense." (with a photo) → create_expense

With Send invoices left off your key, an assistant can prepare everything but physically cannot email a client — you send from Peil yourself.

Local development

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

Peil

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Peil?

Does Peil need an API key?

What transport does Peil use?

When was Peil last checked?

Documentation

Peil MCP server

Draft-by-default

Tools

1. Create your key

2. Install the server

From source

A. With `uv` (no install step)

B. With `pipx` (isolated global command)

C. Plain `venv` + `pip` (works with only stock Python)

3. Connect your assistant

Claude Desktop

Claude Code (CLI)

Cursor

Windsurf

Cline / Roo (VS Code)

VS Code (native Copilot agent mode)

Any other MCP client

First prompts

Local development

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Peil?

Does Peil need an API key?

What transport does Peil use?

When was Peil last checked?

Documentation

Peil MCP server

Draft-by-default

Tools

1. Create your key

2. Install the server

From source

A. With uv (no install step)

B. With pipx (isolated global command)

C. Plain venv + pip (works with only stock Python)

3. Connect your assistant

Claude Desktop

Claude Code (CLI)

Cursor

Windsurf

Cline / Roo (VS Code)

VS Code (native Copilot agent mode)

Any other MCP client

First prompts

Local development

A. With `uv` (no install step)

B. With `pipx` (isolated global command)

C. Plain `venv` + `pip` (works with only stock Python)