MCP server for Pipefy

概要 • インストール • 接続先 • MCP サーバー • CLI • エージェントスキル • ドキュメント • 貢献 • 法的事項

---

概要

Claude Code、Cursor、その他の AI エージェントを Pipefy に接続できます。このツールキットには、サインインに使用したアカウントの権限で Pipefy の API を呼び出す MCP サーバー、CLI、GraphQL SDK に加え、一般的な Pipefy ワークフロー向けのエージェントスキルが含まれています。

コンポーネント	パッケージ／パス	用途
MCP サーバー	pipefy-mcp-server	MCP クライアント（Claude Code、Cursor、Claude Desktop など）向けの Pipefy ツールです。https://mcp.pipefy.com/mcp でホストされているほか、カタログ全体を利用する場合はローカルで実行できます。
CLI	pipefy-cli	スクリプトや CI 向けに、MCP のほとんどの機能をターミナルコマンドとして利用できます。対応範囲と MCP 専用ツールについては、docs/parity.mdをご覧ください。
SDK	pipefy	MCP サーバーと CLI で共有される GraphQL クライアント、サービス、モデルです。
スキル	plugins/pipefy/skills/	一般的な Pipefy ワークフロー向けの Markdown プレイブック（Anthropic Skills 形式）です。

フィードバックや問題の報告：GitHub Issues · [email protected]

---

インストール

お使いのクライアントに該当する行を選び、コマンドを実行してください。フラグ、注意事項、残りの手順については、docs/install.mdをご覧ください。

利用環境	方法	まず実行すること
Claude Code、最速で開始	ホステッド MCP	claude mcp add --transport http --scope user --client-id pipefy-mcp pipefy https://mcp.pipefy.com/mcp
Claude Code、スキル、スラッシュコマンド、CLI を利用	Claude Code プラグイン	/plugin install pipefy --marketplace pipefy/ai-toolkit（Claude Code 2.1.275 以降。古いバージョン向けの2段階の手順はインストールガイドに記載されています）；/pipefy:installで CLI を追加し、/pipefy:pipefy-loginでサインインします
Cursor	Cursor Marketplace プラグイン	Cursor Marketplace からPipefyをインストールします
ローカルファイル用ツールまたは CLI が必要な場合に、macOS または Linux で Cursor、Claude Desktop、または Codex を利用	クイックインストールスクリプト	--client cursor、claude-desktop、または codexを指定してインストールスクリプトを実行します
ターミナル、スクリプト、または CI	CLI のみ	uv tool install pipefy-cliを実行し、続けてpipefy auth loginを実行します
Markdown 対応のエージェント、プレイブックのみ	スキルのみ	npx skills add pipefy/ai-toolkit

Pipefy MCP サーバーは、ホステッド URL、ローカルサーバー、プラグインのいずれか1つだけを同時に登録してください。スキャンコマンドを実行すると、そのマシンにすでに設定されているものを確認できます。設定は変更されません。削除または別の方法への切り替えについては、docs/uninstall.mdをご覧ください。

ホステッドサーバーでは、クライアントの OAuth プロンプトを通じてサインインします。ローカルで利用する場合は、pipefy auth login（ブラウザー OAuth）、無人利用向けのサービスアカウント、またはPIPEFY_TOKENを使用します。詳細は、docs/config.mdとdocs/cli/auth.mdをご覧ください。

---

ツールキットの接続先とインストール内容

ネットワークトラフィックは、インストール時とダウンロードする URL を指定した場合を除き、Pipefy のホストと、Pipefy が発行するストレージ URL に送信されます。

• app.pipefy.com（または PIPEFY_BASE_URL のホスト。api.pipefy.com も同じ応答を返します）：サインイン中のユーザー、サービスアカウント、または PIPEFY_TOKEN の権限で呼び出す、Pipefy の GraphQL API です。MCP ツールとイントロスペクションが失敗した場合に限り使用される pipefy-api-fallback スキルでは、使用するものを伝えたうえで、エージェントがサービスアカウントまたはトークンを PIPEFY_* 環境変数から読み取り、curl でこの API を直接呼び出します。GraphQL リクエストには User-Agent: pipefy-sdk/<version> (<surface>)、X-Client-Name、X-Client-Version が含まれます。また、MCP サーバーは実行場所（(mcp; local) または (mcp; hosted)）と X-Client-Deployment も通知します。ツールキットはこれ以外のテレメトリーを送信しません。
• mcp.pipefy.com：Pipefy のホスト型 MCP サーバーです。Hosted MCP パスと両方のプラグインで使用されます。サインインには、公開クライアント ID pipefy-mcp を使ったブラウザー OAuth を使用します。
• signin.pipefy.com（または PIPEFY_AUTH_URL の発行者）：pipefy auth login はブラウザーを開き、127.0.0.1 でリダイレクトを受信します。CLI とローカル MCP サーバーはここでセッションを更新し、pipefy auth logout はセッションを失効させます。これらのリクエストには User-Agent: pipefy-auth/<version>、X-Client-Name: auth、X-Client-Version が含まれます。
• ipaas.pipefy.com（または PIPEFY_IPAAS_URL のホスト）：iPaaS（Advanced Automations）ツールです。
• ファイル転送：添付ファイルとナレッジベースのアップロード先は、Pipefy が発行する署名付きストレージ URL です。渡された file_url はツールがダウンロードするか、ホスト型パスでは Pipefy のサーバーがダウンロードします。レポートとジョブのエクスポートは、署名付き Pipefy リンクからダウンロードされます。

インストーラーと pipefy auth login がマシンに追加するもの：

• クイックインストールスクリプト（macOS と Linux）：uv がない場合は、astral.sh からインストールする前に確認します。uv のインストーラーは、シェルのプロファイルに ~/.local/bin を追加することがあります。GitHub API から最新の非アルファ版リリース（または --version タグ）を読み込み、そのリリースの wheel を使って pipefy-cli と pipefy-mcp-server に対して uv tool install を実行します。これには pipefy、pipefy-auth、pipefy-infra の wheel が含まれます。サードパーティの依存関係は PyPI から取得され、Python 3.11 以降が見つからない場合、uv が Python インタープリターをダウンロードすることがあります。--client cursor、claude-desktop、または codex を指定すると、そのクライアントの設定に pipefy エントリーを書き込みます（すでに存在する場合を除きます）。uninstall.sh 用に、実行記録を ~/.local/state/pipefy/install-receipt に保存し、npx skills add の実行前に確認します（--no-skills でスキップできます）。
• /pipefy:install（Claude Code プラグイン）：PyPI から uv tool install --force pipefy-cli を実行する前に確認します。
• スキャンコマンド（pipefy-toolkit-setup スキルと docs/uninstall.md）：GitHub 上のこのリポジトリから uninstall.sh をダウンロードし、--scan を指定して実行します。このスクリプトは、OS のキーチェーンを含め、対象範囲に記載されているすべての場所を読み取り、見つかったものを表示します。何も変更しません。
• npx skills add：サードパーティの skills ツールを npm から、このリポジトリを GitHub からダウンロードし、エージェント用のスキルをインストールします。DISABLE_TELEMETRY または DO_NOT_TRACK が設定されていない場合、skills ツールは独自の使用状況テレメトリーを skills.sh に送信します。
• pipefy auth login：Python の keyring を使ってセッションを保存します。通常は OS のキーチェーンに保存されます。PIPEFY_KEYCHAIN_BACKEND=file を指定すると、Pipefy の設定フォルダーにある keyring.cfg というプレーンテキストファイルに保存されます。keyring が OS のキーチェーンを見つけられないマシンでは、ユーザーデータフォルダー内の python_keyring/keyring_pass.cfg（Linux では ~/.local/share）という独自のプレーンテキストファイルにフォールバックすることがあります。ログインとトークンの更新では、Pipefy の設定フォルダー（~/.config/pipefy、または Windows では %APPDATA%\pipefy）に refresh.lock というロックファイルも保持されます。

---

MCP サーバー

ローカルサーバーは、カタログ全体を登録します（正式な名前は registry.py の PIPEFY_TOOL_NAMES です）。ホスト型 URL では、リモートから安全に利用できる範囲が提供されます。つまり、マシン上のファイルを読み込むツール（ナレッジベースのドキュメントのアップロード、カスタム LLM プロバイダーの作成と更新）以外のすべてです。ここでは、添付ファイル用ツールは file_path の代わりに file_url を使用します。

ドメインごとのツールリファレンス：docs/mcp/。共通の規約：docs/mcp/tools/cross-cutting.md。ローカルサーバーで使用するツールを絞り込む方法：ツールの選択。

---

コマンドラインインターフェイス

pipefy CLI は、docs/parity.md で提供済みとされている MCP の機能に対応しています。ほとんどのコマンドは、デフォルトで Rich テーブルを出力し、--json を指定すると JSON を出力します。破壊的な操作を行うコマンドでは、--yes を指定すると確認プロンプトがスキップされます。指定しない場合は、対話形式の確認が引き続き実行されます。pipefy graphql exec は、--yes が設定されていない場合、ミューテーションの実行を拒否します。

pipefy pipe list --json
pipefy card get 123456789
pipefy introspect query pipe

ガイド：docs/cli/ および packages/cli/README.md。

---

エージェントスキル

plugins/pipefy/skills/ には、Markdown を読み取るあらゆるエージェント向けのワークフロープレイブック（前提条件、ツールの表、手順、成功基準）が用意されています。カタログ：plugins/pipefy/README.md。作成ガイド：plugins/AGENTS.md。

---

ドキュメント

ドキュメント	説明
docs/install.md	すべてのインストール方法、それらの切り替え、ツールの選択、チェックアウトから Claude Code プラグインをテストする方法について詳しく説明します。
docs/README.md	MCP、CLI、SDK ごとのドキュメント一覧と共通ガイドです。
docs/config.md	PIPEFY_* 環境変数、config.toml のスキーマとパス、優先順位です。
docs/parity.md	MCP ツールと CLI コマンドの対応表です。
docs/uninstall.md	uninstall.sh --scan と削除方法、およびホスト型、ローカル、プラグインチャネルの切り替えについて説明します。
docs/MIGRATION.md	既存の MCP ユーザー向けの注意事項です。設定との互換性は維持されます。
AGENTS.md	リポジトリの構成、開発ワークフロー、コントリビューターとエージェント向けのガイドラインです。
RELEASE.md	バージョン管理とリリースプロセスです。

---

コントリビューション

イシューやプルリクエストによるコントリビューションを歓迎します。コミットには DCO のサインオフ（git commit -s）が必要です。スキルについては CONTRIBUTING.md をご覧ください。MCP、CLI、SDK については AGENTS.md をご覧ください。ツールが対応していないフィールドタイプがある場合は、そのフィールドタイプと期待する動作を添えてイシューを作成してください。

---

法的事項

このツールキット（MCP サーバー、CLI、SDK、スキル／ブループリントのプレイブック）は、Apache License 2.0 に基づいてライセンスされています。商標に関する留保については、NOTICE をご覧ください。

このツールキットを通じた Pipefy プラットフォームへのアクセスおよび利用には、Pipefy Solutions Terms and Conditions（ポルトガル語版）が適用されます。また、AI 機能には、許容される利用に関する規定を含む Pipefy AI Additional Terms（公開後、参照により同規約に組み込まれる予定）が適用されます。このツールキットを利用するには Pipefy アカウントが必要です。Apache 2.0 ライセンスは、Pipefy サービスの利用権を付与するものではありません。

テンプレートであり、助言ではありません。 スキルとブループリントは、一般的な情報提供を目的とする、設定可能なテンプレートです。これらは法律、人事、財務、税務、その他の専門的な助言を構成するものではなく、本番環境で使用する前に、資格を有する専門家によるレビュー、設定、検証が必要です。公開される各ブループリントには、その想定用途、対象外の用途、AI リスク分類、デフォルトの人間による監督設定を記載した COMPLIANCE.md が含まれます（docs/compliance/COMPLIANCE.template.md を参照）。

AI 生成の出力。 AI 機能が生成する出力には誤りや欠落が含まれる可能性があるため、依拠する前に必ず独自に検証してください。

ベータ版ソフトウェア。 1.0 より前のリリースは「現状有姿」で提供され、いかなる種類の保証もありません。また、いつでも変更または提供終了となる可能性があります。免責事項の全文については、TERMS.md をご覧ください。

セキュリティに関する報告については、SECURITY.md をご覧ください。貢献については、CONTRIBUTING.md をご覧ください。