pipedrive-mcp

pipedrive-mcp

Pipedrive CRM を MCP ツールとして利用できます。取引先、人物、会社を検索して情報を書き込み、パイプラインで取引を進められます。

Model Context Protocol を標準入出力経由で話す単一の Go バイナリです。クライアントごとにネゴシエーションされるプロトコルリビジョン 2026-07-28（現行版）から 2024-11-05 までに対応しています。お使いのマシン上でクライアントのサブプロセスとして実行され、1 つの Pipedrive ワークスペースを対象にします。名前で検索して、ほかのすべての処理に必要な ID を取得し、取引、人物、組織、アクティビティ、メモを、ワークスペースで設定した名前のカスタムフィールドやラベル付きのドロップダウン値とともに読み取れます。それらの作成や編集、取引のパイプライン内での移動（成立、失注、再開、または別のステージへの移動）も行えます。

pipedrive-mcp を選ぶ理由

Pipedrive 独自の API は 2 種類あります。現行の v2 と、提供終了日である 2026-07-31 がすでに過ぎた v1 です。このサーバーは v2 に準拠し、ほかに手段がない機能、つまりメモと whoami による検索だけを例外として切り出しています。この 4 つのツールはサポートが終了した API 上で動作しますが、現在も応答があります。また、v2 には /notes も /users も公開されていないため、移行先もありません。どちらの例外も、呼び出し箇所と CHANGELOG.md に記載しています。記録されていない v1 依存関係は移行されないからです。いずれかから 410 が返った場合は、リクエストを責める検証エラーではなく、提供終了時期を示す [gone] として届きます。

ツールの設計は、独自の流儀ではなく、リリース済みの Google Workspace MCP サーバーに合わせています。読み取りは個別のツールで行い、すべての変更は action を指定する 1 つの manage_ ツールを通じて実行し、書き込みを拒否する際には理由を説明します。モデルがすでに目にしている可能性が高いのはこうしたサーバーであり、それらに合わせることで、説明がなくてもこのサーバーを理解しやすくなります。

Pipedrive には元に戻す機能がないため、書き込みにはガードを設けています。 すべての書き込みでは、対象を先に読み取り、値がすでに入っているフィールドを置き換えないよう拒否します。上書きを指定していない場合は、保護対象の各フィールドを明示します。対処できない拒否はバグです。

以下のすべてのツールは、テストで使うフェイクだけでなく、実際の Pipedrive ワークスペースに対しても実行して検証しています。読み取り、リソース、ガードによる拒否、リハーサルの経路、および対応する各リソースでの元に戻せる書き込みが対象です。この一連のテストは今では手順ではなく Go テストスイートとして実装されており、internal/integration/ に -tags=integration を付けて実行する形で用意されています。make integration で実行できます。ただし、制約が 2 つあります。書き込みの検証には、タグに加えて PIPEDRIVE_INTEGRATION_WRITES=1 の指定が必要です。これを指定しない実行では読み取り部分のみが検証されます。稼働中の CRM への書き込みは自動ではなく、意図的に選択するものです。また、検証したワークスペースは 1 つだけなので、そこにはないカスタムフィールドや権限の設定は未検証です。

インストール

go install github.com/mmedum/pipedrive-mcp/cmd/pipedrive-mcp@latest

これにより、バイナリは Go の bin ディレクトリに配置されます。このディレクトリは PATH に含まれていないことがよくあります。次のコマンドで command not found と表示された場合は、フルパスを使うか、ディレクトリを一度だけ追加してください。

"$(go env GOPATH)/bin/pipedrive-mcp" --version    # check it landed
export PATH="$(go env GOPATH)/bin:$PATH"          # or add it to your shell profile

または、最新リリースから署名済みアーカイブを取得してください。Linux、macOS、Windows 向けに amd64 と arm64 用が用意されています。バイナリを PATH に配置してください。リリースの真正性を確認せずに信用する必要はありません。

# One signature over the checksum file, keyless, tied to the release
# workflow's own identity on a tag. Check it first: until it passes, the
# checksums are only what the release says now.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github\.com/mmedum/pipedrive-mcp/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

# --ignore-missing, because checksums.txt covers every archive and every
# SBOM, and you will have downloaded one of them. On macOS, use
# shasum -a 256 -c in place of sha256sum -c.
sha256sum -c checksums.txt --ignore-missing

# And the archive itself carries build provenance.
gh attestation verify pipedrive-mcp_X.Y.Z_linux_amd64.tar.gz --owner mmedum

Pipedrive をセットアップする

サーバーは、JSON 設定にトークンを貼り付けるよう求めるのではなく、API トークンを OS のキーリング（Linux では libsecret、macOS では Keychain、Windows では Credential Manager）に保存します。詳細なリファレンスと検証ルールについては、docs/configuration.md を参照してください。

pipedrive-mcp login
# Pipedrive workspace subdomain (e.g. acme for acme.pipedrive.com): your-subdomain
# Pipedrive API token for "your-subdomain": ········
# login: token stored in OS keyring (service=pipedrive-mcp, account=your-subdomain)
# login: default domain recorded in ~/.config/pipedrive-mcp/config.json

ドメインのプロンプトを省略するには、--domain your-subdomain を渡すか、PIPEDRIVE_COMPANY_DOMAIN を設定します。スクリプトで使う場合に便利です。

その後、MCP クライアントの設定にワークスペースのドメインやトークンを記載する必要はありません。どちらもキーリングと、機密情報を含まない小さなポインターファイル（os.UserConfigDir()/pipedrive-mcp/config.json）から解決されます。pipedrive-mcp status を実行して確認するか、pipedrive-mcp logout を実行して消去してください。

記録済みのドメインをシェルで一時的に上書きし、別のワークスペースを使う場合は、PIPEDRIVE_COMPANY_DOMAIN を設定します。環境変数は userconfig のポインターより優先されます。CI、オートメーション、または別のトークンを一度だけ使う場合は、PIPEDRIVE_API_TOKEN を設定します。gh や aws の CLI と同様に、環境変数はキーリングより優先されます。

クライアントを接続する

Claude Desktop

pipedrive-mcp login でトークンをキーリングに保存し、デフォルトのドメインをユーザー設定に記録した後は、Claude Desktop の設定に何も記載する必要はありません。シークレットもドメインも不要です。

{
  "mcpServers": {
    "pipedrive": {
      "command": "/usr/local/bin/pipedrive-mcp"
    }
  }
}

特定のワークスペースに固定する場合（たとえば、複数のワークスペースを保存している場合）、env に PIPEDRIVE_COMPANY_DOMAIN を追加すると、この MCP サーバーに限り、記録済みのデフォルトを上書きできます。

設定

すべての設定は PIPEDRIVE_* 環境変数です。デフォルト値と検証ルールを含む全項目の一覧は、docs/configuration.md を参照してください。以下は、サーバーの動作を変える設定です。

環境変数	必須	デフォルト	用途
PIPEDRIVE_COMPANY_DOMAIN	login を使用しない場合のみ	—	サブドメイン（例：acme.pipedrive.com の場合は acme）。pipedrive-mcp login の実行後はユーザー設定に記録されるため、環境変数で指定する必要はありません。
PIPEDRIVE_API_TOKEN	いいえ	—	CI／オートメーション用のフォールバックです。対話的に使う場合は pipedrive-mcp login を推奨します。
LOG_LEVEL	いいえ	info	debug／info／warn／error。
LOG_FORMAT	いいえ	text	text／json。
PIPEDRIVE_DRY_RUN	いいえ	false	サーバー全体のドライランの下限です。すべての書き込みがリハーサルになります。呼び出しごとの dry_run で有効にできますが、無効にはできません。
PIPEDRIVE_HTTP_TIMEOUT	いいえ	30s	リクエストごとの送信 HTTP タイムアウト。

ツール

ツールは20個です。読み取り操作は個別のままで、変更操作はすべてactionを指定する1つの manage_ツールを通じて行います。これはGoogle Workspace MCP サーバーの構成方法と同じです。

まずはsearchを使ってください。 自然言語の窓口として、名前を他のすべてのツールで必要となる数値IDに変換します。「Acmeの取引」を探すためにlist_dealsを使うのはよくある間違いです。これは絞り込みを行うもので、名前との照合はしません。

ツール	内容
search	取引、人物、組織、製品、ファイル、リードを対象としたフリーテキスト検索。名前をIDに変換するために使います
whoami	トークンがどのアカウントとして動作し、どのワークスペースを参照しているかに加え、アクティビティの期限時刻が記録されるタイムゾーンを返します
get_deal	1件の取引を返します。金額、通貨、ステータス、ステージ、関連する人物と会社、ワークスペースでの名称によるカスタムフィールドを確認できます。ドロップダウンはラベルで返されます
list_deals	ステータス、パイプライン、ステージ、担当者、人物、組織、または更新期間で取引を取得します。カーソルによるページネーションに対応しています。アーカイブ済みの取引は専用のコレクションにあるため、archivedを指定してください
manage_deal	取引の作成、編集、ステージ間の移動、成約、アーカイブ、削除を行います。create、update、move_stage、mark_won、mark_lost、reopen、archive、unarchive、deleteに対応しています。カスタムフィールドは名前で、ドロップダウンはラベルで指定します
get_person	1件の連絡先を返します。名前、ラベル付きのすべてのメールアドレスと電話番号、所属する会社、カスタムフィールドを確認できます
list_persons	担当者、関連する組織、または更新期間で人物を取得します。カーソルによるページネーションに対応しています
manage_person	連絡先の作成、編集、削除を行います。create、update、deleteに対応しています。名前はname、またはfirst_name／last_nameで指定し、両方を同時に指定しないでください。カスタムフィールドは名前で、ドロップダウンはラベルで指定します
get_organization	1件の会社を返します。Pipedriveが解析した住所、所属する人物の数、カスタムフィールドを確認できます
list_organizations	担当者または更新期間で会社を取得します。カーソルによるページネーションに対応しています
manage_organization	会社の作成、編集、削除を行います。create、update、deleteに対応しています。カスタムフィールドは名前で、ドロップダウンはラベルで指定します
get_activity	1件の通話、メール、ミーティング、またはタスクを返します。場所、参加者、会議の詳細を確認できます
list_activities	ステータス、担当者、取引、人物、組織、リード、または更新期間でアクティビティを取得します。指定がない限り、メモは除外されます
manage_activity	アクティビティの作成、編集、完了、削除を行います。create、update、complete、reopen、deleteに対応しています
get_note	1件のメモを返します。HTML、作成者、関連するレコードを確認できます
list_notes	関連するレコード、作成者、日付範囲、または更新期間でメモを取得します
manage_note	メモの作成、編集、削除を行います。create、update、deleteに対応しています
list_pipelines	トークンから参照できるすべてのパイプラインを返します。ページネーションはありません。ワークスペースに20個もあることはめったにありません
list_stages	パイプラインのステージと、それぞれにPipedriveが設定した取引確度を返します
refresh_field_cache	PipedriveのUIでカスタムフィールドが追加、名前変更、または拡張された後に、カスタムフィールド名とドロップダウンのラベルを再読み込みします

ガード付き書き込み

Pipedriveには元に戻す機能がないため、拒否だけが唯一のガードです。各 manage_ ツールは書き込む前に対象を読み取り、見えないまま書き込みによって 破棄される内容があれば拒否します。拒否には、保護しているフィールドと 書き込みを許可する引数の2つが必ず示されます。実行に移せない拒否はバグです。

• dry_run は書き込みによって検出・変更される内容を報告し、 何も送信しません。
• overwrite は更新で置き換えてよいフィールドを指定します。たとえば ["title", "value"] のように、拒否で列挙された内容をそのまま指定します。 列挙された数より少ないフィールドしか指定しなかった場合、指定しなかった フィールドについては引き続き拒否されるため、タイトルの置き換えに同意しても、 値の置き換えに同意したことにはなりません。空のフィールドを埋めても何も 破棄されないため、許可は不要です。
• expect_version は書き込みの判断材料となった読み取り時の update_time を 渡し、それ以降にレコードが変更されていた場合は拒否します。ベストエフォートです。 Pipedriveには比較と設定の機能がないため、同時編集は検出できますが、意図的な 競合状態までは防げません。

名前付きの遷移である mark_won、mark_lost、move_stage、reopen、 archive、unarchive、complete は、変更するフィールドが指定したフィールド そのものであるため、overwrite を受け取りません。意図的に後戻りできない操作は ありません。取引の reopen は mark_won と mark_lost を取り消し、アクティビティの complete も取り消せます。ただし、取引の lost_reason はクリアしません。Pipedriveでは 取引が失注状態の場合にしかこのフィールドを受け付けないため、最後に失注した理由の テキストは、新しい理由で再び失注するまでレコードに残ります。例外は manage_note の delete で、これは論理削除です。Pipedrive v1は active_flag を クリアし、get_note は引き続きノートを返します。また、ここではフラグを元に戻す 操作はありません。

ガード付き書き込みが停止すると、[refused] のタグが付いて返されます。これは 独自のエラークラスであり、モデルは検証エラーや上流エラーと区別できます。一方には 再試行しても無駄ですが、もう一方は再試行が適切です。

リソース

レコードをツール呼び出しではなくアタッチするクライアント向けに、5つのリソース テンプレートが get_ ツールと同じものを提供します。

pipedrive://deals/{id}          pipedrive://organizations/{id}
pipedrive://persons/{id}        pipedrive://activities/{id}
pipedrive://notes/{id}

ツールと同じコードを共有しているため、レコードの説明に食い違いが生じることは ありません。URIではツールのオプションである include_attendees と include_notes を渡せないため、これらには引き続きツールが必要です。

ここにないもの

安定したインターフェースだけでは約束の半分にすぎません。もう半分を示すため、以下に一覧を示します。以下に挙げるものは報告すべき見落としではなく、それぞれが設計上の判断または API の制限です。

ツールのないリソース。 プロダクト、リード、ファイル、プロジェクト、目標は、それ自体がマイルストーンです。search ではプロダクト、ファイル、リードを見つけることができます。item_type がそれらを対象としているため、名前から ID を取得できますが、その後にできることは何もありません。試す前に知っておくとよいでしょう。

まったくモデル化されていないリソースで、1.x では対応予定のないもの：webhook、メールとメールスレッド、サブスクリプションと継続収益、保存済みフィルター、通貨、案件からリードへの変換、フォロワー、管理対象のリレーションとしての案件参加者、カスタムフィールド定義の作成や変更（値の読み取りと書き込みはできますが、定義には対応していません）。

レコードのマージには対応していません。 Pipedrive では 2 件の人物または 2 件の組織をマージできますが、このサーバーではできません。その理由は API ではなく、ガードの契約にあります。マージでは、呼び出し元が読み取っていないレコードを含め、一方のレコードのフィールド値がもう一方のレコードの値に置き換えられて消失します。失われる内容を事前に示せる拒否方法はありません。

値が設定されたフィールドをクリアすることはできません。 Pipedrive v2 は null を拒否し、空文字列を値として保存するため、フィールドの変更はできますが、空にすることはできません。

API 自体ではできないことが 2 つあります。再試行しても解決しません。 アクティビティの種類はサーバー側でフィルタリングできません（行を取得してから type でフィルタリングしてください）。また、アクティビティは search のインデックス対象ではありません（list_activities から取得してください）。

Pipedrive の検索インデックスには削除済みレコードが残り、削除済みであることを示す情報は返されません。 削除済みの組織は無期限にインデックスに残り、削除済みの人物もしばらくの間は残ります。そのため、search は検索結果を /organizations と /persons に照合し、存在しないものを除外します。ページに含まれる種類ごとに追加の呼び出しが 1 回発生し、どちらも含まれないページでは呼び出しは発生しません。案件は確認しません。/deals はアーカイブ済みの案件を除外しますが、それらは有効なレコードであるため、確認すると有効なレコードまで除外してしまいます。Pipedrive は削除済みの案件を独自のインデックスから除外します。プロダクト、ファイル、リードは、照合に使う list_ ツールがないため、確認せずに返されます。Pipedrive のページング後に除外が行われるため、ページの件数が少なくなったり、next_cursor が設定されたまま空になったりすることがあります。空のページが終わりとは限りません。

4 つのツールは、サポート終了を過ぎた Pipedrive API v1 を使用しています。 v2 には /notes と /users がないため、get_note、list_notes、manage_note、whoami が該当します。これらは 1.0 の互換性保証の対象外です。CHANGELOG.md を参照してください。

安全性

• すべての書き込みは、呼び出し時にそれぞれガードします。 dry_run は、書き込みで何が見つかり、何が変更されるかを報告し、何も送信しません。すでに存在する内容を更新で置き換えるには overwrite が必要です。また、読み取り後にレコードが変更されていた場合、expect_version は書き込みを拒否します。登録はもはやゲートではありません。存在しないツールは、実行しない理由を説明できないため、拒否処理が代わりに説明します。
• PIPEDRIVE_DRY_RUN は下限であり、デフォルトではありません。 すべての書き込みツールがこれを尊重します。呼び出しごとの dry_run で、1 回の書き込みをリハーサルとして実行できます。フラグが設定されている間は、通信経由でこれをオフにできません。そのため、モデルが何を要求しても、「設定すればサーバーは書き込めない」という状態が保たれます。
• 標準出力には MCP JSON-RPC フレームだけが流れます。 これは MCP の標準入出力トランスポート自体のルールであり、forbidigo がこれを強制します。プロセスのストリームが指定されているのは main だけです。誤って出力が混入するとストリームが破損し、クライアントは通知なく動作を停止します。
• 誤ったサブコマンドを指定すると、サーバーを起動して成功を報告するのではなく、ゼロ以外の終了コードで終了します。

仕組み

MCP client ──stdio──► pipedrive-mcp
                       ├── tools       one handler per tool; shapes the reply
                       ├── server      SDK wiring and the registered surface
                       ├── pipedrive   REST client for the v2 and v1 APIs
                       ├── config      every setting, from environment and flags
                       ├── credentials the API token: keyring, file, environment
                       └── userconfig  the non-secret profile

ヘルプの利用

pipedrive-mcp status を実行してください。解決されたワークスペース、ドメインの取得元、トークンが見つかったかどうかとその保存先、起動時の認証プローブが Pipedrive に到達したかどうかが表示されます。これらは、初回実行時に発生する問題の大半を把握するための情報です。status --json を実行すると、サーバーの起動前に認証済みかどうかを判断する必要があるスクリプト向けに、同じ情報が単一の JSON オブジェクトで出力されます。分岐条件には credentials.resolved を使用し、probe.ran でチェックがスキップされたのか、失敗したのかを判別できます。出力形式については docs/configuration.md を参照してください。

そのほか、知っておくとよい情報は次のとおりです。

• 起動時に 401 Unauthorized が発生し、すぐに終了する。 API トークンが無効、失効済み、または別のワークスペース用です。トークンを修正して再起動してください。サーバーはプロセスの実行中にトークンの変更を確認しません。
• custom_field "Region" not found が発生する。 キャッシュが古くなっています。refresh_field_cache ツールを呼び出すと、サーバーを再起動せずに案件／人物／組織のフィールドメタデータを並行して再取得できます。
• LLM の動作が予想外である。 MCP トランスポートにはユーザーのプロンプトが含まれないため、サーバーログから LLM がツールを呼び出した理由を特定することはできません。stderr のリクエスト ID と MCP クライアントのプロンプトログを照合し、意図を再構成してください。

手順書と運用ガイダンスについては、docs/operations.md を参照してください。

それでも原因が分からない場合は、 issue を登録してください。API トークン、会社のドメイン、レコードの内容は絶対に貼り付けないでください。代わりに、どのような形式の情報かを説明してください。セキュリティ上の問題は、SECURITY.md を通じて非公開で報告してください。

バージョニング

ツール名、引数、出力形式はメジャーバージョン内で安定しています。この約束は 1.0.0 から適用されます。今後、変更にはメジャーバージョンの更新が必要です。1.0.0 より前は、マイナーリリースでもツールのインターフェースが変更される可能性がありました。ツール名の変更、引数の移動、クライアント設定内のコマンド変更など、利用者側で対応が必要な変更には、リリースノートの作成元となる CHANGELOG.md で BREAKING と記載します。修正が適用されるバージョンについては SECURITY.md を参照してください。

開発

make build     # the binary
make test      # race detector, per-package coverage floor
make check     # everything CI runs
make smoke     # drive the built binary over stdio and read the reply

make check が完了の基準です。gofmt、go vet、golangci-lint、パッケージごとのカバレッジ下限を設定したレーステスト、govulncheck、ライセンスの許可リスト、作業ツリー内に実在するアカウントのデータらしきものがないかを確認する漏えいチェック、すべてのアクションをコミット SHA に固定し、インストールするすべてのツールを厳密なバージョンに固定するチェック、依存関係の固定バージョンの古さを確認するチェック、インストール可能なバンドルがスキーマ、パッカーがステージングするファイル、サーバー独自の設定に準拠していること、およびリリースがこのファミリーの 6 つのアーカイブとその名前に準拠していることを確認するマニフェストチェック、変更履歴のバージョン見出しを確認するリンクチェック、stdio のスモークテストを実施します。CI ではさらに、ベースブランチとの差分スキーマチェックを行い、ツールのインターフェースに対する変更が未承認の場合は失敗します。また、変更履歴チェックにより、ソースの変更に [Unreleased] の項目がない場合も失敗します。

規約については CONTRIBUTING.md を、ビルド、テスト、リリースについては docs/development.md と docs/release.md を参照してください。

ドキュメント

• docs/architecture.md — 設計、その根拠となる証拠、フェーズ計画。
• docs/configuration.md — すべての設定。
• docs/development.md — ビルドとテスト。
• docs/operations.md — 実運用での実行方法。
• docs/release.md — リリースの作成方法。
• docs/security.md — 脅威モデル。

コントリビューション

• CONTRIBUTING.md — PR の手順、チェックリスト、Phase 0 のスパイクチェックリスト、サンドボックスアカウントの所有者。
• docs/development.md — ローカル実行ガイド：前提条件、make check、サンドボックスを使ったエンドツーエンド検証、Claude Desktop の接続設定。

セキュリティ

• 脆弱性を報告する前に、SECURITY.md をお読みください。
• トークンの取り扱いと脅威モデルについては、docs/security.md をお読みください。

行動規範

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

ライセンス

Apache License 2.0。