CRM PipeRun

MCP PipeRun

PipeRun CRM API との完全な連携。

---

n8n をお使いですか？ n8n 連携の完全ガイドはこちら

ステップごとのインストール手順、実践例、すぐに使えるワークフロー、エンドポイントの完全なリファレンスを掲載しています。

---

2 つのバージョンをご用意

バージョン	ディレクトリ	対象ユーザー
MCP サーバー	piperun-mcp-server/	Claude Desktop、Claude Code、Cursor
HTTP サーバー	piperun-http-server/	n8n、Zapier、Make、REST API

どちらを選べばよいですか？

• Claude、Cursor、または別の MCP クライアントをお使いですか？ → MCP サーバーをお使いください
• n8n、Zapier、Make をお使いですか？または REST API が必要ですか？ → HTTP サーバーをお使いください

---

MCP サーバー（Claude/Cursor 向け）

AI アシスタントが PipeRun と直接やり取りできるようにする、MCP（Model Context Protocol）サーバーです。

リソース

• PipeRun を完全に管理するための32 個のツール
• deals、persons、companies、activities、notes の完全な CRUD
• 商談と人物の検索
• 整形済みの応答 - 生の JSON ではなく、読みやすい要約を返します
• 指数バックオフによる自動リトライで堅牢性を向上
• 柔軟な認証 - 環境変数または呼び出しごとに指定
• 完全な型定義を備えたTypeScript
• Vitest による自動テスト
• GitHub Actions によるCI/CD

前提条件

• Node.js v18 以上
• npm（通常は Node.js と一緒にインストールされます）
• PipeRun API トークン

インストール

1. リポジトリをクローンします：

git clone https://github.com/dinhogehm/mcp-piperun.git
cd mcp-piperun

2. 依存関係をインストールしてビルドします：

cd piperun-mcp-server
npm install
npm run build

API トークンの取得方法

1. PipeRun アカウントにログインします
2. 設定 > 連携 > API に移動します
3. API トークンをコピーします

設定

オプション 1：環境変数（推奨）

環境に PIPERUN_API_TOKEN を設定します：

{
  "mcpServers": {
    "piperun": {
      "command": "node",
      "args": ["/caminho/para/mcp-piperun/piperun-mcp-server/build/index.js"],
      "env": {
        "PIPERUN_API_TOKEN": "seu_token_aqui"
      }
    }
  }
}

オプション 2：呼び出しごとにトークンを指定

各ツールの呼び出し時に、引数として api_token を渡します。

設定ファイルの場所

• Claude Desktop（MacOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）： %APPDATA%/Claude/claude_desktop_config.json
• Claude Desktop（Linux）： ~/.config/Claude/claude_desktop_config.json
• Claude Code： .claude/settings.json

利用可能なツール（合計 32 個）

商談（Deals）- 7 個のツール

ツール	説明
list_deals	フィルターを指定して商談を一覧表示します
get_deal	商談の詳細を取得します
create_deal	商談を作成します
update_deal	商談を更新します
delete_deal	商談を削除します
search_deals	タイトルで検索します
list_deal_sources	商談の流入元を一覧表示します

人物（Persons）- 6 個のツール

ツール	説明
list_persons	人物／連絡先を一覧表示します
get_person	人物の詳細を取得します
create_person	人物を作成します
update_person	人物を更新します
delete_person	人物を削除します
search_persons	名前／メールアドレスで検索します

企業（Companies）- 5 個のツール

ツール	説明
list_companies	企業を一覧表示します
get_company	企業の詳細を取得します
create_company	企業を作成します
update_company	企業を更新します
delete_company	企業を削除します

アクティビティ - 6 個のツール

ツール	説明
list_activities	アクティビティを一覧表示します
get_activity	アクティビティの詳細を取得します
create_activity	アクティビティを作成します
update_activity	アクティビティを更新します
delete_activity	アクティビティを削除します
list_activity_types	アクティビティの種類を一覧表示します

メモ - 3 個のツール

ツール	説明
list_notes	メモを一覧表示します
create_note	メモを作成します
delete_note	メモを削除します

その他 - 5 個のツール

ツール	説明
list_pipelines	パイプラインを一覧表示します
list_stages	ステージを一覧表示します
list_items	商品を一覧表示します
list_users	ユーザーを一覧表示します
list_custom_fields	カスタムフィールドを一覧表示します
list_tags	タグを一覧表示します
list_loss_reasons	失注理由を一覧表示します

使用例

> Liste minhas oportunidades abertas

[12345] Projeto ABC | R$ 50.000 | Aberta | Etapa: Negociação | Responsável: João
[12346] Contrato XYZ | R$ 25.000 | Aberta | Etapa: Proposta | Responsável: Maria

📊 Total: 2 | Página: 1/1

> Crie uma oportunidade "Novo Cliente" no funil 1, etapa 1, responsável 100

✅ Oportunidade criada com sucesso!
[12347] Novo Cliente | Sem valor | Aberta | Etapa: Prospecção | Responsável: João

> Busque pessoas com nome "Silva"

🔍 Busca por "Silva":

[100] João Silva | [email protected] | 11999999999 | Empresa: ABC Ltda
[101] Maria Silva | [email protected] | Sem contato | Empresa: N/A

📊 Total: 2 | Página: 1/1

開発

# Instalar dependências
npm install

# Compilar
npm run build

# Modo watch (recompila automaticamente)
npm run watch

# Executar linter
npm run lint

# Formatar código
npm run format

# Executar testes
npx vitest run

# Depuração com MCP Inspector
npm run inspector

プロジェクト構成

mcp-piperun/
├── .github/
│   └── workflows/
│       └── ci.yml              # GitHub Actions CI/CD
├── piperun-mcp-server/
│   ├── src/
│   │   ├── index.ts           # Código principal
│   │   └── __tests__/         # Testes
│   ├── build/                  # Código compilado
│   ├── eslint.config.js       # Configuração ESLint
│   ├── vitest.config.ts       # Configuração Vitest
│   ├── .prettierrc            # Configuração Prettier
│   ├── package.json
│   └── tsconfig.json
├── .gitignore
└── README.md

変更履歴

v0.3.0

• 削除ツール（deal、person、company、activity、note）を追加
• アクティビティツール（get、create、update）を追加
• 検索ツール（search_deals、search_persons）を追加
• 指数バックオフによるリトライ（3 回）を追加
• 環境変数 PIPERUN_API_TOKEN による認証を追加
• 読みやすい要約を含む形式でレスポンスを整形
• ESLint + Prettier の設定
• Vitest による自動テスト
• GitHub Actions による CI/CD

v0.2.0

• ツールを追加：list_persons、get_person、update_person、get_deal、create_deal、update_deal
• リクエストのタイムアウトを 30 秒に設定
• すべての操作で引数を検証

v0.1.0

• 基本ツールを含む初期バージョン

---

HTTP サーバー（n8n/Zapier/Make 向け）

従来の HTTP リクエストによる連携に対応した HTTP/REST サーバーです。

クイックインストール

cd piperun-http-server
npm install
npm run build

実行

# Com variável de ambiente
PIPERUN_API_TOKEN=seu_token npm start

# Servidor roda em http://localhost:3000

n8n での使用

1. HTTP サーバーを起動します
2. n8n で HTTP Request ノードを使用します
3. 次のように設定します：
   • URL： http://localhost:3000/deals
   • Header： X-PipeRun-Token: seu_token

主なエンドポイント

リソース	エンドポイント
取引	GET/POST /deals、GET/PUT/DELETE /deals/:id、POST /deals/search
人物	GET/POST /persons、GET/PUT/DELETE /persons/:id、POST /persons/search
会社	GET/POST /companies、GET/PUT/DELETE /companies/:id
アクティビティ	GET/POST /activities、GET/PUT/DELETE /activities/:id
メモ	POST /notes、DELETE /notes/:id
パイプライン	GET /pipelines、GET /stages

Docker

docker build -t piperun-http-server ./piperun-http-server
docker run -p 3000:3000 -e PIPERUN_API_TOKEN=seu_token piperun-http-server

📖 完全なドキュメント： piperun-http-server/README.md

---

参考資料

• PipeRun API ドキュメント
• Model Context Protocol（MCP）
• TypeScript 用 MCP SDK

ライセンス

このプロジェクトはオープンソースとして公開されています。