# Peil

> Peil is a freemium MCP server for finance and payments. MCP server for Peil: log hours, draft invoices and check finances as a Dutch freelancer. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Freemium
- **Platforms:** CLI, API
- **Website:** https://peil.app/en/docs/mcp
- **Repository:** https://github.com/luminc/peil-mcp
- **MCP Registry name:** app.peil/peil-mcp
- **Categories:** finance and payments, productivity
- **Listing updated:** 2026-11-15

## About

Peil's server is a thin local client of the Peil public API, started with `uvx peil-mcp` and authenticated by a scoped API key created under Settings, Developer. Its tools cover reads such as unbilled hours, invoice lists, expenses and an orientation snapshot of what is outstanding, overdue and drafted, plus writes for hours, clients, expenses and invoices.

The design is draft-first. `draft_invoice` only creates a draft, and anything that emails a client sits behind a separate `invoices:send` scope, so a key without it can never send. Write operations are rate-limited, with hours at 60 a minute, drafts at 20 and sends at 10. Every action appears in the activity log next to the key, and revoking the key cuts access immediately.

Expenses are entered as the receipt reads, with the total, Dutch btw and a category. The README says the server and keys are free on every plan, while features that are Pro in Peil, such as emailing invoices and recurring invoices, stay Pro when driven through a key.

## Features

- **Scoped API keys:** Separate scopes for read, hours, clients, expenses, invoices and sending.
- **Draft-only invoices:** Invoices are created as drafts and nothing reaches a client without the send scope.
- **Timesheet tools:** Log, edit and delete hours, using the client's default rate unless one is given.
- **Receipt expenses:** Add an expense with total, Dutch btw and category from a receipt the assistant reads.
- **Financial snapshot:** Check outstanding, overdue, draft and year-to-date positions.
- **Activity log:** Every action taken with a key shows in the log next to it.

## Good for

- Log billable hours by prompt at the end of a work day
- Draft a month's invoice for one client from unbilled hours
- Ask how much is outstanding and what has been invoiced this year
- File an expense from a receipt with Dutch btw
- Write payment reminder copy in a chosen tone

## Install

### Claude Code (Terminal)

```sh
claude mcp add peil-mcp --env PEIL_API_KEY='<PEIL_API_KEY>' -- uvx peil-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "peil-mcp": {
      "command": "uvx",
      "args": [
        "peil-mcp"
      ],
      "env": {
        "PEIL_API_KEY": "<PEIL_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "peil-mcp": {
      "command": "uvx",
      "args": [
        "peil-mcp"
      ],
      "env": {
        "PEIL_API_KEY": "<PEIL_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "peil-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "peil-mcp"
      ],
      "env": {
        "PEIL_API_KEY": "<PEIL_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "peil-mcp": {
      "command": "uvx",
      "args": [
        "peil-mcp"
      ],
      "env": {
        "PEIL_API_KEY": "<PEIL_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "peil-mcp": {
      "command": "uvx",
      "args": [
        "peil-mcp"
      ],
      "env": {
        "PEIL_API_KEY": "<PEIL_API_KEY>"
      }
    }
  }
}
```

## Tools

- `list_clients`: List your clients
- `get_client_details`: Show one client's details including default rate
- `list_unbilled`: List unbilled hours per client for a period
- `list_invoices`: List invoices by status or client
- `orientation_snapshot`: Show outstanding, overdue, drafts and year-to-date position
- `get_reminder_copy`: Read custom reminder email copy and schedule
- `list_expenses`: List a year's one-off expenses and which lack receipts
- `log_hours`: Add a timesheet entry
- `edit_hours`: Edit a timesheet entry
- `delete_hours`: Delete a timesheet entry
- `create_client`: Create a client
- `update_client`: Update a client
- `delete_client`: Delete a client
- `create_expense`: Add an expense from a receipt
- `draft_invoice`: Draft an invoice from unbilled hours
- `set_invoice_status`: Change an invoice status without emailing
- `update_invoice`: Edit due date, payment date or notes
- `delete_invoice`: Delete an invoice
- `archive_invoice`: Archive an invoice
- `set_reminder_copy`: Write custom reminder copy for a tone and language
- `send_invoice`: Email an invoice to the client now
- `schedule_send`: Schedule a draft to be emailed later
- `cancel_scheduled_send`: Cancel a scheduled send
- `send_reminder`: Email a payment reminder

## FAQ

### Can the assistant email my clients?

Only if the key has the separate Send invoices scope; otherwise it can create drafts only.

### Is the MCP server free?

The README says keys and the server are free on every plan, though Pro features stay Pro.

### What do I need to run it?

Python 3.11 or newer with uv or pipx, and a Peil API key in PEIL_API_KEY.

### Which assistants work with it?

Claude Desktop, Claude Code, Gemini CLI, Codex CLI and other clients that can launch a local MCP command.

### Is Peil free?

Peil has a free plan, with paid plans for more usage or features.

### How do I add Peil to Claude Code?

Run this command in your terminal: claude mcp add peil-mcp --env PEIL_API_KEY='<PEIL_API_KEY>' -- uvx peil-mcp

### What are the best alternatives to Peil?

The closest alternatives to Peil are Ha MCP, Concord MCP, Solana MCP by Vybe, Tapetide - Indian Stock Market MCP and Budget Tracker.

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Solana MCP by Vybe](https://ai-powered.com/mcp/solana-mcp-by-vybe): Solana MCP by Vybe is an MCP server for finance and payments.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [Budget Tracker](https://ai-powered.com/mcp/budget-tracker-2): Budget Tracker is a freemium MCP server for finance and payments.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [Quantivex Research](https://ai-powered.com/mcp/quantivex-research): Quantivex Research is a free MCP server for finance and payments.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.

---
Source: https://ai-powered.com/mcp/peil
