mcp-pipedrive

Pipedrive MCP サーバー

Claude 向けの、最も包括的で堅牢な Pipedrive MCP 実装です

Model Context Protocol に対応した、本番環境ですぐに使えるサーバーです。Claude から Pipedrive CRM API に包括的にアクセスできます。このサーバーを使うと、自然言語での会話を通じて、営業ワークフローの自動化、取引の管理、連絡先の整理、アクティビティの追跡をシームレスに行えます。

Nubiia が開発・保守しています — negocios 向けの AI 自動化と連携（MCP、Holded、Pipedrive など）。自社向けにも導入したいですか？ nubiia.es までお問い合わせください。

特長

• 29 カテゴリーにわたる 300 以上のツール - Pipedrive REST API 全体（v1 + v2）を網羅
• 高度なレート制限 - 1 秒あたり 10 リクエスト、最大 100 リクエストのバーストに対応
• マルチレベルキャッシュ - 頻繁にアクセスされるデータを 5～15 分間キャッシュ
• リトライロジック - リクエスト失敗時（429、500、502、503、504）の指数バックオフ
• 包括的なエラー処理 - 実行可能な提案を含む詳細なエラーメッセージ
• TypeScript の完全サポート - 全体で型安全なスキーマとインターフェースを提供
• Zod による検証 - すべての入力を実行時に検証し、分かりやすいエラーメッセージを表示
• MCP リソース - パイプライン、カスタムフィールド、ユーザー情報への読み取り専用アクセス
• MCP プロンプト - 一般的な操作向けの 5 つのガイド付きワークフロー
• パフォーマンス指標 - リクエスト時間と成功率を組み込みで追跡
• 読み取り専用モード - すべての書き込み操作をブロックするオプションの安全モード
• ツールセットのフィルタリング - 必要に応じて特定のツールカテゴリーを有効化／無効化

ツールカテゴリー

29 カテゴリーにわたる 307 個のツール — Pipedrive REST API 全体（v1 + v2）を網羅します。

カテゴリ	ツール数	説明
取引	43	ライフサイクル全体：CRUD、ステージ、参加者、製品、ファイル、統合、コンバージョン、分割払い（v2）
フィールド	30	カスタムフィールドの検出、取引／人物／組織／製品／プロジェクトの各フィールドの CRUD、さらにリードとメモのフィールド
人物	23	カスタムフィールド、アクティビティ、取引、ファイル、フォロワーを含む連絡先管理
組織	21	人物、取引、アクティビティとの関係を含む企業管理
プロジェクト	16	プロジェクト、ボード、フェーズ、グループ、タスク、プラン管理
パイプライン	15	パイプライン管理、ステージ、コンバージョンと移動の統計
リード	15	リードの CRUD、ラベル、ソース、検索、リード↔取引のコンバージョン
ロール	14	ロール、割り当て、設定、パイプラインの表示範囲
製品	13	製品カタログ、取引／人物への添付、ファイル、フォロワー
ユーザー	12	ユーザー、権限、フォロワー、ロールの割り当て
メモ	9	取引、人物、組織向けのメモとコメント
アクティビティ	9	期限と完了状況を含むタスク、通話、会議のスケジュール設定
システム	9	ヘルス、メトリクス、通貨、ユーザー設定、最近使用した項目、キャッシュ
チーム	8	チーム管理とメンバーシップ
ファイル	7	ファイルのアップロード、ダウンロード、管理、リモートファイルへのリンク
フィルター	7	フィルターの CRUD と補助メタデータ
検索	6	ユニバーサル検索とエンティティ固有の検索
メールボックス	6	メールスレッドとメッセージ
ステージ	5	パイプラインステージの CRUD（v2）
タスク	5	プロジェクトのタスク管理
目標	5	目標の CRUD と結果
通話ログ	5	通話ログの CRUD と音声添付ファイル
アクティビティタイプ	5	アクティビティタイプの管理
組織間の関係	5	組織間の関係
チャネル	4	メッセージングチャネルの統合
Webhook	3	Webhook の CRUD
権限セット	3	権限セットの確認と割り当て
プロジェクトテンプレート	2	プロジェクトテンプレートの検出
会議	2	ビデオ通話プロバイダーとの連携

インストール

グローバルインストール

npm install -g @nubiia/mcp-pipedrive

npx を使用する（インストール不要）

npx -y @nubiia/mcp-pipedrive

設定

前提条件

1. 設定 > API から Pipedrive API トークンを取得します
2. Claude Desktop をインストールします

Claude Desktop のセットアップ

macOS

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Windows

%APPDATA%\Claude\claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

環境変数

変数	必須	デフォルト	説明
PIPEDRIVE_API_TOKEN	はい	-	Pipedrive API トークン
PIPEDRIVE_READ_ONLY	いいえ	false	読み取り専用モードを有効にします（すべての書き込み操作をブロックします）
PIPEDRIVE_TOOLSETS	いいえ	deals,persons,organizations,activities	有効にするツールカテゴリをカンマ区切りで指定します
LOG_LEVEL	いいえ	info	ログレベル（debug、info、warn、error）

高度な設定例

読み取り専用モード

探索目的での使用や、誤った変更を防ぎたい場合に最適です。

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "PIPEDRIVE_READ_ONLY": "true"
      }
    }
  }
}

ツールセットの絞り込み

特定のツールカテゴリのみを有効にします。

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "PIPEDRIVE_TOOLSETS": "deals,persons,search"
      }
    }
  }
}

デバッグログ

トラブルシューティング用に詳細なログを有効にします。

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-pipedrive"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "your_token",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

使用例

例 1：連絡先を指定して取引を作成する

Claude, create a new deal for "Enterprise Software License" worth $50,000.
The contact is John Smith ([email protected]). Set the expected close date
to the end of next month and add a follow-up call for tomorrow.

Claude は次の処理を行います。

1. 「John Smith」を検索するか、新しい人物として作成します
2. その人物に紐づけて取引を作成します
3. 明日の通話アクティビティを予定します
4. ID と次のステップを含む概要を提示します

例 2：連絡先を検索する

Find all contacts at Acme Corporation and show me their recent deals.

Claude は次の処理を行います。

1. 組織から「Acme Corporation」を検索します
2. その組織に関連付けられているすべての人物を取得します
3. 各人物の取引を取得します
4. 合計を含む整理された結果を提示します

例 3：アクティビティを管理する

Show me all overdue activities for my open deals and reschedule them
to next week.

Claude は次の処理を行います。

1. done=false で期限を過ぎているすべてのアクティビティを一覧表示します
2. オープン中の取引に紐づいているアクティビティに絞り込みます
3. 各アクティビティの日付を翌週の新しい日付に更新します
4. 日程を変更した項目の概要を提示します

例 4：カスタムフィールドを使用する

Before creating this deal, show me what custom fields are available
for deals and explain what each one means.

Claude は次の処理を行います。

1. pipedrive://custom-fields リソースにアクセスします
2. 取引固有のカスタムフィールドを抽出します
3. フィールド名、タイプ、選択肢を表示します
4. 取引の作成時にそれらを使用する方法を説明します

例 5：パイプラインを管理する

Generate a pipeline report showing deal counts and total values for
each stage in my sales pipeline.

Claude は次の処理を行います。

1. pipedrive://pipelines リソースを使用します
2. ステージごとにグループ化された取引の概要を取得します
3. 合計と割合を計算します
4. 読みやすいレポートにまとめます

例 6：週次レビューのワークフロー

Run the weekly pipeline review prompt.

Claude は次の処理を行います。

1. weekly-pipeline-review プロンプトを実行します
2. ステージごとにすべてのオープン中の取引を集めます
3. 指標（受注／失注、成約間近、停滞中の取引）を計算します
4. 実行可能な提案を生成します

カスタムフィールド

取引、人物、組織、製品、リードの作成時または更新時に、表示名でカスタムフィールドの値を渡します。

{
  "title": "ACME Enterprise Deal",
  "value": 50000,
  "currency": "USD",
  "custom_fields": {
    "Industria": "Tech",
    "Budget": 50000
  }
}

MCP サーバーが、名前を Pipedrive のハッシュキーに自動的に変換します。詳しくは、完全なガイドである docs/CUSTOM_FIELDS.md を参照してください。

ステージとリードラベルの管理

LLM から直接、パイプラインのステージとリードラベルを管理できます。

{ "name": "Qualified", "pipeline_id": 1, "deal_probability": 75 }

非同期の *_convert_to_* ／ *_convert_status ツールのペアを使用して、条件を満たしたリードを取引に変換できます（または、取引をリードに戻せます）。

取引の分割払い

取引の予定された固定支払いを管理します（API v2 — 従来のサブスクリプション機能を置き換える最新機能です）。

{ "id": 123, "description": "Deposit", "amount": 500, "billing_date": "2026-01-15" }

ツール：deals_list_installments、deals_add_installment、deals_update_installment、deals_delete_installment。

すべてのフィールドを網羅

フィールドツールがすべてのエンティティに対応しました。案件、人物、組織、製品、リード、メモのフィールド一覧（fields_list_lead_fields、fields_list_note_fields — 読み取り専用）に加え、API v2 によるプロジェクトフィールドの完全な CRUD（fields_list_project_fields、fields_create_project_field、fields_update_project_field、fields_delete_project_field）を利用できます。

アーキテクチャ

コアコンポーネント

• PipedriveClient - レート制限、キャッシュ、再試行ロジックを備えた HTTP クライアント
• レートリミッター - Bottleneck ベースのリミッター（10 リクエスト/秒、バースト容量あり）
• キャッシュレイヤー - TTL ベースのキャッシュと LRU による削除（最大 500 件）
• 再試行ハンドラー - 一時的なエラーに対する指数バックオフ
• メトリクスコレクター - リクエストの追跡とパフォーマンスの監視
• エラーハンドラー - コンテキスト付きの標準化されたエラー形式

ツールの構造

各ツールは、一貫したパターンに従います。

1. Zod スキーマ - 詳細なエラーメッセージを伴う入力検証
2. 説明 - LLM 向けの詳細な使用方法
3. ハンドラー - PipedriveClient を呼び出す非同期関数

リソース

3 つの MCP リソースで、読み取り専用の参照データを提供します。

• pipedrive://pipelines - ステージと案件数を含むすべてのパイプライン
• pipedrive://custom-fields - すべてのエンティティのカスタムフィールド定義
• pipedrive://current-user - 認証済みユーザーの情報と権限

プロンプト

よく使われる操作向けに、5 つのガイド付きワークフローを用意しています。

• create-deal-workflow - 人物とアクティビティを含む、案件作成の一連の手順
• sales-qualification - BANT による評価チェックリスト
• follow-up-sequence - 複数日にわたるアクティビティの連続実行
• weekly-pipeline-review - パイプラインの健全性レポート
• lost-deal-analysis - 失注案件のパターン分析

パフォーマンス

レート制限

• デフォルト：毎秒 10 リクエスト（リクエスト間隔 100ms）
• バースト：毎分補充される 100 トークンのリザーバー
• 自動再試行：429 エラーは 5 秒後に自動で再試行されます

キャッシュ戦略

データ型	TTL	理由
パイプライン	10 min	パイプラインの構造は頻繁には変わりません
カスタムフィールド	15 min	フィールド定義は比較的安定しています
ユーザー情報	1 min	セッション中にユーザーデータが変わる場合があります
リストリクエスト	5 min	ページネーション結果のデフォルト

メトリクス

サーバーは次の項目を追跡します。

• リクエストの合計数と成功率
• 平均応答時間
• 種類別のエラー率
• キャッシュヒット率
• レート制限の発生回数

system/metrics ツールでメトリクスにアクセスできます。

API リファレンス

この MCP サーバーは Pipedrive REST API v1 を実装しています。詳しい API ドキュメントについては、以下をご覧ください。

• Pipedrive API リファレンス
• Pipedrive API 変更履歴
• レート制限

高度な使い方

カスタムフィールドの確認

エンティティを作成または更新する前に、利用可能なカスタムフィールドを確認してください。

// Access via MCP resource
//custom-fields

// Or use field tools
pipedrive: fields / deal - fields;
fields / person - fields;
fields / org - fields;
fields / activity - fields;

エラー処理

すべてのツールは、次の情報を含む構造化エラーを返します。

• エラーの種類（検証、認証、レート制限など）
• 詳細なメッセージ
• 推奨される対応
• 元の API エラー（該当する場合）

ワークフローの自動化

複雑なワークフローでは、複数のツールを連携させます。

1. リードの評価

   • 人物を検索する
   • 関連する案件とアクティビティを取得する
   • 評価メモを作成する
   • 案件のステージを更新する

2. 案件のパイプライン移動

   • 案件の詳細を取得する
   • カスタムフィールドの要件を確認する
   • カスタムフィールドを更新する
   • 次のステージに移動する
   • 次のアクティビティを作成する

3. レポート作成

   • ステージ別に案件を一覧表示する
   • 案件の概要を取得する
   • メトリクスを算出する
   • Markdown 形式に整える

トラブルシューティング

よくある問題と解決方法については、TROUBLESHOOTING.mdをご覧ください。

すぐに試せる対処法：

• 認証エラー：https://app.pipedrive.com/settings/api でAPIトークンを確認してください
• レート制限：リクエスト頻度を下げるか、キャッシュを有効にしてください
• 検証エラー：ツールの入力スキーマと必須フィールドを確認してください
• Claude でツールが表示されない：設定を変更した後、Claude Desktop を再起動してください

コントリビューション

コントリビューションを歓迎します！ガイドラインについてはCONTRIBUTING.mdをご覧ください。

開発環境のセットアップ

# Clone the repository
git clone https://github.com/nubiia-dev/mcp-pipedrive.git
cd mcp-pipedrive

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run with auto-reload during development
npm run dev

テストの実行

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run with UI
npm run test:ui

セキュリティ

セキュリティポリシーと脆弱性の報告方法については、SECURITY.mdをご覧ください。

重要：APIトークンをバージョン管理にコミットしないでください。必ず環境変数を使用してください。

Nubiia について

この MCP サーバーは Nubiia が構築し、メンテナンスしています。

Nubiiaは、企業のプロセスの自動化とAIによるツール連携を支援しています。カスタム MCP サーバー、CRMやERP（Pipedrive、Holdedなど）との連携、ビジネスデータをClaudeなどのアシスタントにつなぐエージェントを提供しています。この @nubiia/mcp-pipedrive は、私たちの取り組みを示すオープンソースの例です。

👉 ビジネス向けのAI連携や自動化をご希望ですか？ nubiia.es · ✉️ [email protected]

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細はLICENSEファイルをご覧ください。

クレジット

Holded CRM向けの優れた MCP サーバー実装であるmcp-holdedに着想を得ています。

サポート

• Nubiia — AI自動化と連携：nubiia.es
• 問題：GitHub Issues
• ディスカッション：GitHub Discussions
• ドキュメント：docs/

変更履歴

バージョン履歴とリリースノートについては、CHANGELOG.mdをご覧ください。

ロードマップ

• リアルタイム更新のためのWebhookサポート
• 一括更新のためのバルク操作
• 複雑なクエリによる高度なフィルタリング
• エクスポート／インポート機能
• 他のCRMとの連携
• GraphQL サポート

作成者

Nubiia が開発 — nubiia.es · [email protected]

メンテナー：Samuel Fraga — GitHub

---

Nubiiaが心を込めて作成