Connect Peil to your AI assistant (MCP)

The Peil MCP server connects Peil to your AI assistant. MCP is an open standard — Claude, ChatGPT (OpenAI) and Gemini all speak it. Once connected, you can just ask your assistant to act on your Peil account:

• "Log 3 hours for Bright Agency today: built the API integration."
• "Draft an invoice for De Correspondent covering June."
• "How much is outstanding, and what have I invoiced this year?"

Draft-first, by design

The assistant works through an API key with its own scopes. Creating and sending invoices are deliberately separate permissions: without Send invoices (invoices:send), an assistant can only ever create drafts. Nothing reaches your clients without you reviewing it in Peil first. Every operation is recorded in the key's usage history.

Step 1 — create an API key

In the Peil app, go to Settings → Developer settings (Pro) and create a key with the Read, Log hours and Manage invoices scopes. If you also want the assistant to manage clients or send email, add Manage clients and Send invoices respectively. Sending is a separate scope because it is client-facing and irreversible. Pick a short lifetime (90 days, say) — renewing is one click. The key is shown once, so copy it straight away.

Step 2 — add the server to your assistant

The MCP server runs locally and talks only to the Peil API. With uv or pipx there is nothing to install or clone — uvx peil-mcp runs the latest version on demand (Python 3.11+). Every tool, scope and configuration option is listed on the peil-mcp‑page on PyPI.

The server is the same for every assistant: the command uvx peil-mcp with your key in the PEIL_API_KEY environment variable. Only where you configure that differs per assistant.

Claude Desktop — add this to claude_desktop_config.json:

{
  "mcpServers": {
    "peil": {
      "command": "uvx",
      "args": ["peil-mcp"],
      "env": { "PEIL_API_KEY": "your-key" }
    }
  }
}

Claude Code — one command:

claude mcp add peil -e PEIL_API_KEY=your-key -- uvx peil-mcp

Gemini CLI — put the same mcpServers block as above in ~/.gemini/settings.json (or .gemini/settings.json in your project).

ChatGPT / OpenAI (Codex CLI) — one command:

codex mcp add peil --env PEIL_API_KEY=your-key -- uvx peil-mcp

Or by hand in ~/.codex/config.toml under the [mcp_servers.peil] section (note: mcp_servers with an underscore, TOML).

Other clients (Cursor, Windsurf, Cline, VS Code …) use the same command and the same PEIL_API_KEY; only the config file differs. If a client can launch a local MCP command, Peil works.

Step 3 — just ask

The assistant can drive your whole invoicing loop — depending on the scopes on the key: read and manage clients (create, edit, delete), log, edit and delete hours, review unbilled hours, draft invoices, change their status (mark as paid, for instance), delete or archive invoices, and write reminder copy. Anything that puts email in front of a client — sending an invoice, scheduling a send, mailing a reminder — sits behind the separate invoices:send scope and asks for your confirmation first. You don't need to type client names exactly: "Bright" finds Bright Agency, and when in doubt the assistant asks which client you meant.

Worth knowing

• Revoking is immediate. Revoke the key in Developer settings and the assistant loses all access at once.
• The log is your visibility. Every action taken with the key (hours, drafts, sends) appears in the activity log next to that key.
• Limits. Write operations are rate-limited (hours 60/min, drafts 20/min, sending 10/min) — ample for normal use, tight enough to dampen accidents.

Prefer to build against the API directly, without MCP? The full REST reference is in the API reference.