Peil

Peil MCP 服务

mcp-name: app.peil/peil-mcp

将 Peil 连接到 Claude（或任何 MCP 客户端）：记录工时、 根据未开票工时起草发票、根据收据添加费用，并通过提示词 查看当前状况。

• 网站： https://peil.app
• 文档： https://peil.app/en/docs/mcp
• 源码： https://github.com/Luminc/peil-mcp

该服务是 Peil 公共 API 的纯客户端。它使用你在 Peil 的 Settings → Developer 中创建的限定范围 API 密钥进行身份验证。所有套餐都可免费使用密钥和此服务；Peil 中的 Pro 功能（发送发票邮件、 提醒、定期发票）通过密钥使用时仍需要 Pro。

默认创建草稿

draft_invoice 只会创建草稿——不会向你的 客户发送任何内容。发送是单独的工具（send_invoice），并且还需要你的密钥具有单独的 invoices:send 权限。没有此权限的密钥绝不会代表你发送任何邮件。

工具

读取（read）

工具	功能
list_clients	列出你的客户
get_client_details	查看单个客户的详情，包括是否设置了默认费率
list_unbilled	查看某个时段内每位客户的未开票工时
list_invoices	列出发票，可按状态／客户筛选
orientation_snapshot	查看未结清／逾期／草稿／本年迄今的情况
get_reminder_copy	查看你的自定义提醒邮件内容和安排
list_expenses	查看一年的一次性费用，以及哪些费用没有留存收据

工时（timesheet:write）

工具	功能
log_hours	添加工时记录（除非指定费率，否则使用客户默认费率）
edit_hours	编辑记录（仅修改你传入的字段）
delete_hours	删除记录（若记录已计入已发送／已付款的发票，则无法删除）

客户（clients:write）

工具	功能
create_client / update_client / delete_client	客户的增删改查（若客户有项目／已发送的发票，则无法删除）

费用（expenses:write）

工具	功能
create_expense	按收据内容添加费用：总额、荷兰 btw、类别（键或标签）。你的助手可以读取收据；照片本身会保存在 Peil 应用中

发票（invoices:write）

工具	功能
draft_invoice	根据未开票工时起草发票（summary / by_project / per_day）
set_invoice_status	更改状态（例如标记为已付款）——不会向任何人发送邮件
update_invoice	编辑安全字段（到期日、付款日期、备注）
delete_invoice / archive_invoice	删除（已付款的发票无法删除）／归档
set_reminder_copy	为某种语气／语言编写自定义提醒邮件内容

面向客户的邮件（invoices:send——不可撤销，始终先确认）

工具	功能
send_invoice	立即向客户发送发票邮件
schedule_send	安排在未来某个时间发送草稿邮件
cancel_scheduled_send	取消预定发送
send_reminder	为已发送／逾期发票发送付款提醒邮件

---

1. 创建密钥

在 Peil 中：Settings → Developer → 创建具有所需权限的密钥。 建议从读取 + 记录工时 + 起草发票开始（如果你希望助手归档收据，也可以添加添加费用）；除非你确实希望助手向客户发送邮件，否则请勿启用发送发票。稍后你需要将此密钥粘贴到助手的配置中，作为 PEIL_API_KEY。

2. 安装服务

简易方式——无需克隆、无需安装：

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

→ 启动命令为 uvx peil-mcp（或 pipx run peil-mcp）。跳转到 第 3 步。以下内容仅在你 从源码运行时才需要（例如首次发布之前，或想要修改代码时）。

源码

你需要 Python 3.11 或更高版本，以及本地的 mcp-server/ 文件夹副本。 运行 python3 --version 检查你的 Python 版本。

用哪种方法？ 先运行 which uv pipx。如果你已经有 uv，请使用 A — 这是最省事的方式。如果没有，pipx（B）可以提供一个干净的全局命令。如果 两者都没有，而且不想安装工具，纯 venv 方式（C）也能运行，只需使用机器上 已有的 Python。

在下文所有位置，都将 /ABS/PATH/TO/mcp-server 替换为此文件夹的真实绝对路径 （在该文件夹内运行 pwd 即可获取）。

A. 使用 uv（无需安装步骤）

uv 会按需构建和运行，无需预先安装任何内容：

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

→ 你的启动命令是：uv run --directory /ABS/PATH/TO/mcp-server peil-mcp

没有 uv？运行 curl -LsSf https://astral.sh/uv/install.sh | sh（macOS/Linux） 或 pip install uv。

B. 使用 pipx（隔离的全局命令）

pipx 会将服务安装到独立的隔离环境中，并在你的 PATH 上添加 peil-mcp 命令：

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

→ 你的启动命令是：peil-mcp

没有 pipx？运行 python3 -m pip install --user pipx && python3 -m pipx ensurepath。

C. 纯 venv + pip（仅需 Python 自带功能即可运行）

无需额外工具，只需使用你已有的 python3：

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

→ 你的启动命令是：/ABS/PATH/TO/mcp-server/.venv/bin/peil-mcp （等效命令为 /ABS/PATH/TO/mcp-server/.venv/bin/python -m peil_mcp）。

运行时请使用普通的 pip install .（不要使用 -e/可编辑安装）。可编辑安装 依赖 .pth 路径钩子，在某些环境中可能无法加载且不报错，导致出现 ModuleNotFoundError: No module named 'peil_mcp'。只有在修改服务本身时 才需要可编辑安装 — 请参阅 本地开发。

3. 连接你的助手

不同助手之间唯一的变化是配置文件所在的位置。 每个 MCP 客户端都需要相同的三项内容：

• command — 第 2 步中的启动命令
• env — 将 PEIL_API_KEY 设置为第 1 步获取的密钥
• （可选）PEIL_API_URL — 仅当你要连接非生产环境的 Peil 时才需要（参见本地开发）；默认值为 https://api.peil.app/api/v1。

标准配置块（Claude Desktop、Cursor、Windsurf、Cline 及大多数其他客户端均使用） 如下所示 — command + args 只是将启动命令按空格拆分后的内容：

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

编辑 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/， Windows：%APPDATA%\Claude\），添加上述配置块，然后重启 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

-- 后的内容即为启动命令。使用 claude mcp get peil 验证 （查找 Status: ✔ Connected），并在会话中使用 /mcp 重新连接。

Cursor

将标准配置块添加到 .cursor/mcp.json（此项目）或 ~/.cursor/mcp.json（所有项目），然后在 Settings → MCP 中启用 peil。

Windsurf

将标准配置块添加到 ~/.codeium/windsurf/mcp_config.json，然后在 Cascade MCP 面板中点击 Refresh。

Cline / Roo（VS Code）

打开扩展的 MCP Servers → Configure 面板，并将标准配置块添加到 cline_mcp_settings.json。

VS Code（原生 Copilot Agent 模式）

VS Code 使用略有不同的格式 — 在 .vscode/mcp.json 中使用 servers（而非 mcpServers） 和显式的 type：

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

其他 MCP 客户端

为其提供相同的 command + args + PEIL_API_KEY env。该服务通过 stdio 使用 MCP 通信； 只要客户端能够启动 stdio 命令，就能运行 Peil。

首批提示词

连接后，试试：

• “我目前的情况如何？” → orientation_snapshot
• “今天为 De Correspondent 记录 6 小时编辑工作。” → log_hours
• “根据我尚未开票的工时，为 De Correspondent 起草一张发票。” → draft_invoice
• “这是我的火车票，把它添加为一笔费用。”（附带照片）→ create_expense

如果你的密钥未启用 发送发票，助手可以准备好所有内容， 但无法实际向客户发送邮件——你需要自行从 Peil 发送。

---

本地开发

使用 PEIL_API_URL 将服务指向本地后端：

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

如果你在修改服务，可编辑安装会自动应用你的更改， 无需重新安装：

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

测试（使用模拟 HTTP，无需后端——pyproject.toml 中的 pythonpath = ["src"] 设置使测试不受安装方式影响）：

.venv/bin/pytest