Pipedrive MCP Server

Pipedrive MCP サーバー

Pipedrive 向けのシングルテナント、セルフホスト型 Model Context Protocol サーバーです。バージョン 2.x では、案件、人物、組織、パイプライン、ステージ、リード、およびアイテム検索に Pipedrive API v2 を使用します。Pipedrive がこれらの API を v2 に移行していないため、メモとユーザーは明確にスコープされた v1 アダプターの背後に分離されています。

このサーバーはデフォルトで読み取り専用です。対象を限定した 2 つの書き込みツールは明示的に有効化でき、いずれもプレビューを優先します。

要件

• Node.js 22 または 24（Node 24 を推奨）
• Pipedrive API トークン

PIPEDRIVE_DOMAIN は使用されません。公式 Pipedrive クライアントが API のベース URL を指定します。

stdio でインストールして実行する

グローバルにインストールします。

npm install --global pipedrive-mcp-server
PIPEDRIVE_API_TOKEN=your-token pipedrive-mcp-server

または、このリポジトリをビルドします。

npm ci
npm run check
PIPEDRIVE_API_TOKEN=your-token npm start

デスクトップ MCP の設定例：

{
  "mcpServers": {
    "pipedrive": {
      "command": "pipedrive-mcp-server",
      "env": {
        "PIPEDRIVE_API_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP

最新の HTTP エンドポイントのデフォルトは http://127.0.0.1:3000/mcp です。

PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
pipedrive-mcp-server

GET /health は認証不要で、ホストが検証され、サービスのステータスのみを返します。サーバーはセッションごとに独立した MCP サーバーとトランスポートを作成し、シャットダウン時にはアクティブなセッションを終了します。

ループバック以外のアドレスにバインドするには、32 文字以上の HS256 JWT シークレットと、明示的なホスト名許可リストの両方が必要です。

PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=mcp.example.com \
MCP_ALLOWED_ORIGINS=https://app.example.com \
MCP_JWT_SECRET='replace-with-at-least-32-random-characters' \
pipedrive-mcp-server

組み込み HTTP サーバーは TLS を終端しません。信頼できないネットワークに直接公開しないでください。信頼できる HTTPS リバースプロキシの背後に配置し、アプリケーションのポートを非公開に保ち、プロキシが転送ヘッダーを追加ではなく置き換えるよう設定してください。JWT ベアラートークンは取得された場合にリプレイ可能です。そのため Docker Compose はデフォルトでサービスをホストのループバックにのみ公開します。リモートで運用する場合は、バインド先を変更する前に TLS ターミネーターを追加する必要があります。

クライアントは Authorization: Bearer <token> を送信します。トークンは HS256 を使用する必要があります。MCP_JWT_ISSUER と MCP_JWT_AUDIENCE を設定すると、オプションでクレームの検証が追加されます。起動時トークンの設定はありません。

MCP_ALLOWED_ORIGINS は、完全一致するカンマ区切りの許可リストです。空の場合、サーバーは CORS ヘッダーを出力しません。ワイルドカード CORS はサポートされていません。MCP_ALLOWED_HOSTS には、スキーム、パス、ポートを含めず、ホスト名のみを指定します。

レガシー SSE

非推奨の互換性ルートは GET /sse と POST /messages です。2.x ではデフォルトで有効で、MCP_ENABLE_LEGACY_SSE=false で無効にできます。MCP_TRANSPORT=sse は HTTP モードのエイリアスとして引き続き機能し、警告を出力します。これらのルートは 3.0 で削除する予定です。

Docker

.env.example を .env にコピーし、PIPEDRIVE_API_TOKEN と、32 文字以上のランダムな MCP_JWT_SECRET を設定します。その後、次を実行します。

docker compose up --build -d
docker compose ps

Compose はポート 3000 で /mcp を提供し、MCP ルートには JWT を必須とし、権限のない node ユーザーとして実行され、Node の組み込み fetch で /health を確認します。公開イメージには ghcr.io/willdent/pipedrive-mcp-server を使用します。

Docker で stdio を使う場合は、トランスポートを上書きし、HTTP ヘルスチェックを無効にします。

docker run --rm -i --no-healthcheck \
  -e PIPEDRIVE_API_TOKEN=your-token \
  -e MCP_TRANSPORT=stdio \
  ghcr.io/willdent/pipedrive-mcp-server:latest

ツールと応答の仕様

読み取りツール：

• get-users
• get-deals、get-deal、get-deal-notes、search-deals
• get-persons、get-person、search-persons
• get-organizations、get-organization、search-organizations
• get-pipelines、get-pipeline、get-stages
• search-leads、search-all

一覧／検索ツールは、次の形の JSON テキストと構造化コンテンツを返します。

{
  "items": [],
  "count": 0,
  "nextCursor": "optional-cursor",
  "truncated": false,
  "filters": {}
}

単一レコードを返すツールは { "item": {} } を返します。安定したエラーは { "code", "message", "retryable" } を返し、MCP の isError: true を設定します。未加工の API エラー、認証情報、トークンを含む URL は公開されません。

get-deals には、非表示のステータスやアクティビティ日付のデフォルト値はありません。所有者、ステージ、パイプライン、ステータス、更新日時、金額、カーソル、上限、および汎用カスタムフィールド選択をサポートします。ページサイズのデフォルトは 100 で、上限は 500 です。金額によるフィルタリングでは最大 2,000 件の案件をスキャンし、さらにレコードが残っている場合は truncated と nextCursor を報告します。タイトルで検索する場合は search-deals を使用してください。

書き込みの制限

PIPEDRIVE_WRITE_TOOLS に指定されたツール以外は、書き込みツールとして登録されません。

PIPEDRIVE_WRITE_TOOLS=move-deal,add-deal-note

• move-deal には dealId、targetStageId、expectedCurrentStageId が必要です。更新の直前に、ベストエフォートで楽観的な古い状態のチェックを行います。Pipedrive はステージをアトミックに条件付き更新する機能を提供していないため、別のクライアントによる同時変更とこのチェックが競合する可能性があります。
• add-deal-note が受け付けるプレーンテキストは最大 10,000 文字です。送信前に HTML エスケープされます。
• どちらのツールも、デフォルトではプレビューを表示します。変更が実行されるのは execute: true の場合のみです。
• 監査出力には操作、エンティティ ID、結果、タイムスタンプのみが含まれます。メモの内容や認証情報は含まれません。

設定

変数	デフォルト	用途
PIPEDRIVE_API_TOKEN	必須	Pipedrive API トークン
MCP_TRANSPORT	stdio	stdio、http、または非推奨の sse エイリアス
MCP_HOST	127.0.0.1	HTTP バインドアドレス
MCP_PORT	3000	HTTP ポート
MCP_HTTP_PATH	/mcp	Streamable HTTP パス
MCP_ALLOWED_HOSTS	ローカルホスト	ホスト名の完全一致許可リスト
MCP_ALLOWED_ORIGINS	空	CORS オリジンの完全一致許可リスト
MCP_ENABLE_LEGACY_SSE	true	/sse と /messages を維持
MCP_MAX_SESSIONS	100	HTTP/SSE セッションの合計最大数
MCP_SESSION_IDLE_TIMEOUT_MS	1800000	この時間を超えてアイドル状態のセッションを終了
MCP_JWT_SECRET	空	HS256 シークレット。ループバック以外では必須
MCP_JWT_ISSUER	空	任意の JWT 発行者
MCP_JWT_AUDIENCE	空	任意の JWT オーディエンス
PIPEDRIVE_WRITE_TOOLS	空	明示的な書き込みツール許可リスト
PIPEDRIVE_RATE_LIMIT_MIN_TIME_MS	250	キューに入った呼び出し間の最小遅延
PIPEDRIVE_RATE_LIMIT_MAX_CONCURRENT	2	同時呼び出しの最大数

すべてのポート、パス、数値制限、オリジン、ホスト、ブール値、ツール名は起動時に検証されます。

1.x からの移行

1. Node を 22 または 24 にアップグレードします。
2. PIPEDRIVE_DOMAIN、MCP_JWT_TOKEN、MCP_JWT_ALGORITHM、MCP_ENDPOINT を削除します。
3. HTTP の MCP_TRANSPORT=sse を MCP_TRANSPORT=http に置き換えます。クライアントがまだレガシー SSE を使用している場合は、一時的にエイリアスを維持してください。
4. 最新のクライアントの接続先を /mcp に設定します。レガシークライアントは 2.x を通じて /sse を使用できます。
5. カーソルページネーションと構造化レスポンスの仕様に合わせて、呼び出し元を更新します。
6. ディールのクエリを確認します。get-deals は、オープン状態や 365 日間のアクティビティ期間を暗黙的に強制しなくなりました。
7. 各書き込みをレビューし、サンドボックスでテストするまでは、PIPEDRIVE_WRITE_TOOLS を空のままにします。

開発とリリース

npm run typecheck
npm test
npm run build
npm run validate:package

自動、Docker、手動による Pipedrive サンドボックスのゲートについては、docs/release-checklist.md を参照してください。リリースはタグによって管理され、npm の Trusted Publishing と GHCR のセマンティックタグを使用します。

対象範囲

バージョン 2.x は、引き続きシングルテナントでセルフホスト可能です。Pipedrive OAuth、MCP OAuth、永続セッション、広範な CRUD、破壊的な削除ツールは、意図的に対象外としています。

ライセンス

MIT