CRM PipeRun

MCP PipeRun

与 PipeRun CRM API 的完整集成。

---

使用 n8n？ 点击此处查看 n8n 集成完整指南

包含：分步安装、实用示例、现成工作流和完整的端点参考。

---

两种可用版本

版本	目录	适用对象
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）

MCP（Model Context Protocol）服务，可让 AI 助手直接与 PipeRun 交互。

功能

• 32 个工具，全面管理 PipeRun
• 完整的 CRUD，用于管理 deals、persons、companies、activities 和 notes
• 搜索机会和人员
• 格式化的响应——提供易读摘要，而非原始 JSON
• 自动重试，采用指数退避机制，提升可靠性
• 灵活的身份验证——通过环境变量或按调用提供
• TypeScript，提供完整类型
• 自动化测试，使用 Vitest
• CI/CD，使用 GitHub Actions

先决条件

• 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

许可证

本项目以开源形式提供。