Peil

Peil MCP server

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	1 件のクライアントの詳細（デフォルト料金が設定されているかどうかを含む）
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	クライアントの CRUD（プロジェクト／送信済み請求書がある場合、削除不可）

経費（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	1 つのトーン／言語向けにカスタムのリマインダーメール文面を作成

クライアント向けメール（invoices:send — 取り消し不可、必ず事前に確認）

ツール	機能
send_invoice	請求書を今すぐクライアントにメールで送信
schedule_send	下書きを将来の日時にメール送信するようスケジュール
cancel_scheduled_send	スケジュール済みの送信をキャンセル
send_reminder	送信済み／支払期限超過の請求書について、支払いリマインダーをメールで送信

---

1. キーを作成する

Peil で、Settings → Developer に移動し、必要な権限を設定してキーを作成します。まずは read + Log hours + Draft invoices から始めてください（領収書を処理するアシスタントが必要な場合は Add expenses を追加します）。アシスタントにクライアント宛てのメールを送信させたい場合を除き、Send invoices は無効のままにしてください。このキーを、以下のアシスタント設定に 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 クライアントで必要なものは、次の 3 つです。

• command — 手順 2 で確認した起動コマンド
• env — 手順 1 で取得したキーを PEIL_API_KEY に設定
• （任意）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 エージェントモード）

VS Code では、.vscode/mcp.json に mcpServers ではなく servers を使い、type を明示する、少し異なる形式を使用します。

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

その他の MCP クライアント

同じ command + args + PEIL_API_KEY env を指定してください。サーバーは標準入出力経由で MCP と通信します。標準入出力のコマンドを起動できるクライアントであれば、Peil を実行できます。

最初のプロンプト

接続したら、次のことを試してみてください。

• 「今の状況は？」 → orientation_snapshot
• 「今日、編集作業として De Correspondent に6時間分の作業時間を記録して。」 → log_hours
• 「De Correspondent 向けに、請求前の作業時間から請求書の下書きを作成して。」 → draft_invoice
• 「これが電車の切符です。経費として追加して。」（写真を添付）→ create_expense

キーで Send invoices をオフにしておけば、アシスタントはすべての準備を行えますが、 クライアントにメールを送信することはできません。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