MCP server for Pipefy

概览 • 安装 • 连接与安装内容 • MCP 服务 • CLI • Agent 技能 • 文档 • 参与贡献 • 法律信息

---

概览

将 Claude Code、Cursor 和其他 AI Agent 连接到 Pipefy。此工具包包含 MCP 服务、CLI 和 GraphQL SDK，可使用你登录账号的权限调用 Pipefy API；此外还提供适用于常见 Pipefy 工作流的 Agent 技能。

组件	软件包 / 路径	用途
MCP 服务	pipefy-mcp-server	为 MCP 客户端（Claude Code、Cursor、Claude Desktop 等）提供 Pipefy 工具。托管于 https://mcp.pipefy.com/mcp，也可在本地运行以使用完整目录。
CLI	pipefy-cli	以终端命令的形式提供大部分 MCP 功能，适用于脚本和 CI。功能覆盖情况及仅限 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 或更高版本；安装指南提供了适用于较早版本的两步安装方式）；/pipefy:install 会添加 CLI，/pipefy:pipefy-login 会为其登录
Cursor	Cursor Marketplace 插件	从 Cursor Marketplace 安装 Pipefy
在 macOS 或 Linux 上使用 Cursor、Claude Desktop 或 Codex，且需要本地文件工具或 CLI	快速安装脚本	运行安装脚本，并使用 --client cursor、claude-desktop 或 codex
终端、脚本或 CI	仅 CLI	执行 uv tool install pipefy-cli，然后执行 pipefy auth login
任意支持 Markdown 的 Agent，仅需操作手册	仅技能	执行 npx skills add pipefy/ai-toolkit

每次只能注册一个 Pipefy MCP 服务：托管 URL、本地服务或插件三者之一。扫描命令 会报告机器上已有的配置，且不会进行任何更改。移除或切换路径：docs/uninstall.md。

托管服务会通过客户端的 OAuth 提示词引导你登录。本地路径可使用 pipefy auth login（浏览器 OAuth）、用于无人值守场景的服务帐户，或 PIPEFY_TOKEN。参考文档：docs/config.md 和 docs/cli/auth.md。

---

工具包连接和安装的内容

网络流量会发送到 Pipefy 主机和 Pipefy 提供的存储 URL，但安装期间以及你传入 URL 进行下载时除外：

• app.pipefy.com（或 PIPEFY_BASE_URL 中的主机；api.pipefy.com 的响应相同）：Pipefy 的 GraphQL API，调用时使用已登录用户、服务帐户或 PIPEFY_TOKEN 的权限。仅当 MCP 工具和内省失败后才会使用 pipefy-api-fallback 技能，此时 Agent 会通过 curl 直接调用此 API，并在告知你将使用哪种凭据后，从 PIPEFY_* 环境变量读取服务帐户或令牌。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 服务，供托管 MCP 路径和两个插件使用。通过浏览器 OAuth 登录，使用公共客户端 ID pipefy-mcp。
• signin.pipefy.com（或 PIPEFY_AUTH_URL 中的颁发者）：pipefy auth login 会打开浏览器，并在 127.0.0.1 接收重定向。命令行和本地 MCP 服务会在此处刷新会话，pipefy auth logout 会撤销会话。这些请求会携带 User-Agent: pipefy-auth/<version>、X-Client-Name: auth 和 X-Client-Version。
• ipaas.pipefy.com（或 PIPEFY_IPAAS_URL 中的主机）：iPaaS（高级自动化）工具。
• 文件传输：附件和知识库上传会发送到 Pipefy 提供的预签名存储 URL。你传入的 file_url 会由工具下载，或在托管路径下由 Pipefy 的服务端下载。报告和作业导出内容会从 Pipefy 的签名链接下载。

安装程序和 pipefy auth login 会在你的机器上添加以下内容：

• 快速安装脚本（macOS 和 Linux）：如果尚未安装 uv，会先征求许可，再从 astral.sh 安装；uv 安装程序可能会将 ~/.local/bin 添加到你的 shell 配置文件中。脚本会从 GitHub API 读取最新的非 alpha 版本（或 --version 标签），并使用该版本的 wheel 运行 uv tool install，安装 pipefy-cli 和 pipefy-mcp-server，包括其 pipefy、pipefy-auth 和 pipefy-infra wheel。第三方依赖来自 PyPI；如果未找到 Python 3.11 或更高版本，uv 可能会下载一个解释器。使用 --client cursor、claude-desktop 或 codex 时，如果客户端配置中尚无 pipefy 条目，脚本会写入该条目。脚本会将运行记录保存到 ~/.local/state/pipefy/install-receipt，供 uninstall.sh 使用，并会在运行 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 运行。该命令会读取范围下列出的所有来源，包括操作系统钥匙串，并打印查找到的内容。它不会更改任何内容。
• npx skills add：从 npm 下载第三方 skills 工具，并从 GitHub 下载此仓库，然后为你的 Agent 安装技能。除非设置了 DISABLE_TELEMETRY 或 DO_NOT_TRACK，否则 skills 工具会向 skills.sh 发送自己的使用遥测数据。
• pipefy auth login：通过 Python keyring 保存会话，通常保存在操作系统钥匙串中。设置 PIPEFY_KEYCHAIN_BACKEND=file 时，凭据会以明文形式保存到 Pipefy 配置文件夹中的 keyring.cfg 文件。如果 keyring 在某台机器上找不到操作系统钥匙串，它可能会回退到自己的明文文件：用户数据文件夹中的 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_url，而非 file_path。

各领域工具参考：docs/mcp/。通用约定：docs/mcp/tools/cross-cutting.md。将本地服务限定为部分工具：选择工具范围。

---

命令行界面

pipefy CLI 涵盖 docs/parity.md 标记为已交付的 MCP 功能。大多数命令默认输出 Rich 表格，使用 --json 时则输出 JSON。对于具有破坏性的命令，--yes 会跳过提示；不使用时，仍会进行交互式确认。除非设置了 --yes，否则 pipefy graphql exec 不会执行变更操作。

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

指南：docs/cli/ 和 packages/cli/README.md。

---

Agent 技能

plugins/pipefy/skills/ 包含工作流操作指南（前置条件、工具表、步骤和成功标准），适用于任何能读取 Markdown 的 Agent。目录：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	仓库结构、开发工作流，以及面向贡献者和 Agent 的指南。
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 服务的权利。

模板，而非建议。 技能和蓝图是可配置的模板，仅供一般信息参考。它们不构成法律、人力资源、财务、税务或其他专业建议，在投入生产使用前，必须由合格的专业人员进行审查、配置和验证。每个已发布的蓝图都附带一个 COMPLIANCE.md，其中说明其预期用途、不适用范围、AI 风险分类和默认人工监督设置（参阅 docs/compliance/COMPLIANCE.template.md）。

AI 生成的输出。 AI 功能生成的输出可能包含错误或遗漏；在依赖这些输出之前，必须进行独立核实。

测试版软件。 1.0 之前的版本按“原样”提供，不附带任何形式的保证，并且可能随时变更或停止提供。完整免责声明请参阅 TERMS.md。

安全问题报告：请参阅 SECURITY.md。贡献方式：请参阅 CONTRIBUTING.md。