Pipefy MCP Server

Open-source MCP for Pipefy — 128 tools for pipes, cards, tables, relations, automations, AI, observability and more. Alpha · built in public — feedback & issues or dev@pipefy.com

Disclaimer: Community project for developer workflows — not Pipefy’s official or supported integration for external enterprise use.

Table of contents

MCP tools

The server exposes 128 tools, grouped below into nine surface areas. Canonical names live in PIPEFY_TOOL_NAMES (src/pipefy_mcp/tools/registry.py).

Documentation for agents: each tool’s description and Args: come from its Python docstring—MCP clients show that text to LLMs for routing. Use the docstrings (and the per-area docs linked in the table) as the authority on parameters and edge cases.

Cross-cutting behavior

Rules that apply to many tools (pagination, IDs, debug, extra_input, two-step deletes, permissions, introspection, error shape, and more) live in docs/tools/cross-cutting.md. That page also notes dependents on destructive previews when optional scope args (e.g. pipe_id / phase_id) are used. Per-tool parameters stay in docstrings and the category links below.

Getting Started

Prerequisites

• Python 3.11+
• A Pipefy Service Account Token (Generate in Admin Panel > Service Accounts).

Remember to add the service account to the pipe you want the AI to use.

Installation

We recommend using uv for dependency management. Ensure it's installed.

# Clone the repository
git clone https://github.com/gbrlcustodio/pipefy-mcp-server.git
cd pipefy-mcp-server

# Sync dependencies
uv sync

# Optional: copy template and edit (full guide: docs/setup.md)
cp .env.example .env

Setup, env vars, and MCP client JSON: use Setup — single doc for first-time install, Pydantic / .env precedence, and Cursor / Claude examples (keys in .env.example). Optional: ./bootstrap.sh runs uv sync and creates .env from .env.example if missing.

Why these dependencies?

The runtime stack in pyproject.toml is small on purpose. For a longer rationale (code references and security notes), see Dependencies. Summary:

MCP clients

Step-by-step JSON samples and CLI examples are in Setup → MCP client setup.

Development & Testing

Running Tests

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/pipefy_mcp/services/pipefy --cov-report=term-missing

# Integration tests (requires .env with PIPEFY_* OAuth settings)
uv run pytest -m integration -v

# Attachment upload live tests (optional IDs — see tests/tools/test_attachment_tools_live.py)
# uv run pytest tests/tools/test_attachment_tools_live.py -m integration -v

MCP Inspector

npx @modelcontextprotocol/inspector uv --directory . run pipefy-mcp-server

Code Quality

# Lint code
uv run ruff check src/

# Format code
uv run ruff format src/

Adding or renaming an MCP tool

1. Implement the tool in the appropriate module under src/pipefy_mcp/tools/ and call its *Tools.register(...) from ToolRegistry.register_tools() in src/pipefy_mcp/tools/registry.py if it is not already wired.
2. Add the exact tool name (as exposed to MCP clients) to PIPEFY_TOOL_NAMES in the same file. The server uses that set for collision checks at startup and for cleanup after a failed registration; tests/test_server.py also asserts the live tool list matches this set.

Contributing

We are building this in public and we need your feedback!

• Field mapping: If you encounter a complex field type that the Agent doesn't fill correctly, please open an issue.
• New tools: What other Pipefy actions would improve your workflow? Feel free to open an issue or a PR explaining what it is and how you would use it.