Pipefy AI Toolkit

Open-source toolkit for Pipefy developers: a Model Context Protocol (MCP) server for AI agents, a pipefy CLI for terminals and automation, a shared GraphQL SDK, and a catalog of agent skill playbooks.

Overview

Feedback and issues: GitHub Issues · [email protected]

Installation

Pre-1.0 ships pre-release builds to PyPI on every tag; uvx and uv tool install resolve them. A stable PyPI release becomes the default at v1.0. The current pre-release line is v0.3.0-beta.* (latest tag: v0.3.0-beta.1). Two install paths: the Quick install script below (resolves the latest GitHub Release at runtime and runs uv tool install for you), or Claude Code via the plugin marketplace (or hosted MCP).

The CLI snippets below install pipefy-cli from PyPI, which resolves pipefy and pipefy-auth transitively (no explicit --with needed). While the toolkit ships only pre-release versions (the 0.x line), uv resolves the latest pre-release automatically; to pin a specific one, use pipefy-cli==X.Y.Z (PEP 440 form, e.g. pipefy-cli==0.3.0b1). Do not pass a global --prerelease allow: it also lets transitive dependencies jump to their own pre-releases, which can pull a broken build.

Two auth paths:

• Human OAuth (interactive): pipefy auth login runs the browser flow and stores a session in your OS keychain. Works anywhere the pipefy CLI is on PATH (uv tool install once, any client can invoke it). Claude Code additionally exposes it as the /pipefy:pipefy-login slash command via the plugin marketplace. Pipe membership is whatever the signed-in user already has.
• Service account (unattended / CI): provision a Service Account in Pipefy Admin (Admin → Service Accounts) and add that account to every pipe the tools should touch. Wire PIPEFY_SERVICE_ACCOUNT_CLIENT_ID and PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET into the client config below.

Full env-var reference and config.toml precedence: docs/config.md.

First-time / ask your agent: paste a setup request into Claude or Cursor and point them at this section — the checklist is skills/onboarding/pipefy-toolkit-setup/SKILL.md. Pick one MCP registration named pipefy (do not mix hosted HTTP and local stdio/plugin under the same name).

Hosted MCP (Claude Code)

Zero local Python: Claude Code connects over HTTPS. Auth is the client OAuth flow (--client-id pipefy-mcp). Hosted exposes the remote-safe tool surface only.

Do not run this if you already have a local/plugin MCP named pipefy (or another Pipefy stdio entry you intend to keep). Remove the conflicting registration first: claude mcp remove pipefy -s user (adjust name/scope), or use the Claude Code plugin path instead of hosted.

claude mcp add --transport http --scope user \
  --client-id pipefy-mcp \
  pipefy https://mcp.pipefy.com/mcp

Complete the browser login when prompted (claude mcp login pipefy if the client reports Needs authentication). For CLI/slash commands without a second MCP server, use Claude Code instead, or install the CLI only (CLI). Hand-wired local stdio: packages/mcp/README.md.

Quick install (recommended)

One command installs the CLI + MCP server, optionally adds skills, and registers the MCP server in your client config:

curl -fsSL https://raw.githubusercontent.com/pipefy/ai-toolkit/main/install.sh \
  | sh -s -- --client cursor

Replace --client cursor with one of: claude-code, claude-desktop, codex, or none (prints the snippet to paste). Useful flags:

• --yes skip all confirmation prompts.
• --no-skills skip the npx skills add step.
• --version vX.Y.Z pin a specific GitHub Release tag (default: most recent prerelease or release).
• --dry-run print every command without executing.
• --allow-root opt-in for root execution (refused by default).

After install, run pipefy auth login to authenticate (--device on headless systems). The installer puts pipefy-mcp-server on PATH, so each client's config collapses to {"command": "pipefy-mcp-server"}.

Claude Code

/plugin marketplace add pipefy/ai-toolkit
/plugin install pipefy
/pipefy:install
/pipefy:pipefy-login

Type the slash commands in order (the model cannot invoke /plugin … for you). /plugin install pipefy registers the local MCP server and the /pipefy:install + /pipefy:pipefy-login slash commands. /pipefy:install runs uv tool install once to put pipefy on PATH (idempotent). /pipefy:pipefy-login runs the OAuth browser flow. For hand-wired setups (paste-into-config blocks per client, the macOS errSecParam keychain note, the local-clone alternative for contributors), see packages/mcp/README.md.

CLI

Ad-hoc:

uvx --from pipefy-cli pipefy --help

Permanent install:

uv tool install pipefy-cli
pipefy --install-completion bash    # or zsh, fish
pipefy auth login                   # browser OAuth, session in OS keychain

CLI deep-dives (auth precedence, --token / PIPEFY_TOKEN, parity matrix): packages/cli/README.md and docs/cli/.

Skill catalog install

npx skills add pipefy/ai-toolkit                           # all skills
npx skills add pipefy/ai-toolkit --skill pipefy-pipes-and-cards

Catalog and authoring guide: skills/README.md.

Post-1.0 (PyPI preview)

uvx pipefy-mcp-server
uv tool install pipefy-cli

Deprecation and semver (post-1.0): docs/DEPRECATION.md.

Repository layout

uv workspace with three Python packages and a skills catalog. pipefy is the vendor GraphQL layer; MCP and CLI depend on it and do not import each other.

MCP server

The server registers 182 tools across thirteen domains. Canonical names: PIPEFY_TOOL_NAMES in packages/mcp/src/pipefy_mcp/tools/registry.py.

Tool descriptions and Args: blocks come from Python docstrings (what MCP clients show to models). Per-area reference docs cover parameters, edge cases, and cross-cutting behavior.

Shared conventions (pagination, IDs, permissions, error shape): docs/mcp/tools/cross-cutting.md.

Command-line interface

The pipefy CLI mirrors shipped MCP capabilities where parity is defined in docs/parity.md. Conventions: Rich output by default, --json for scripts, --yes on destructive commands.

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

CLI-specific guides: docs/cli/ (including introspect-then-execute).

Agent skills

The skills/ directory holds workflow playbooks: prerequisites, tool tables (MCP + CLI), steps, and success criteria. Compatible with any agent that reads Markdown (Cursor, Claude Code, Codex, and others). Distribution is via skills.sh (55+ agent targets); install commands are under Installation above.

Full catalog: skills/README.md. Authoring: skills/AGENTS.md. Contributions: CONTRIBUTING.md.

Card & phase agent ergonomics: use skills/pipes-and-cards/pipefy-pipes-and-cards/SKILL.md (workflow Seed pipe across phases; prefer dedicated tools over execute_graphql).

Documentation

Development

Install uv if you don't have it, then from the repository root:

uv sync
[[ -f .env ]] || cp .env.example .env   # first-time setup; then fill in PIPEFY_SERVICE_ACCOUNT_*
uv run pytest -m "not integration"    # unit tests (no live API)
uv run pytest -m integration -v     # live API (requires PIPEFY_*)
uv run ruff check . && uv run ruff format .

MCP Inspector (protocol debugging):

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

Adding an MCP tool: implement under packages/mcp/src/pipefy_mcp/tools/, register in ToolRegistry, add the name to PIPEFY_TOOL_NAMES, and ship the matching CLI command (or document a deferral in docs/parity.md). See AGENTS.md for the full TDD workflow.

Test the Claude Code plugin from a local checkout

The Claude Code install adds the marketplace from the pipefy/ai-toolkit GitHub repo, which tracks main. To run your local branch (e.g. dev) as the plugin instead, point the marketplace at your clone:

/plugin marketplace add /absolute/path/to/ai-toolkit
/plugin install pipefy@pipefy

Whatever is checked out in that clone — any branch — is what loads. Use the plugin@marketplace form (pipefy@pipefy) since the marketplace and the plugin share the name pipefy. After editing plugin files (skills, commands), run /reload-plugins to pick up changes without restarting.

Already installed the GitHub version? A marketplace named pipefy can be registered only once, and a marketplace declared in ~/.claude/settings.json under extraKnownMarketplaces is locked — /plugin marketplace add becomes a no-op (already on disk — declared in user settings) and keeps pointing at GitHub. Run /plugin marketplace remove pipefy first (or delete that extraKnownMarketplaces entry), then add the local path.

Contributing

Contributions are welcome via issues and pull requests.