Skip to content

pipefy/ai-toolkit

BranchesTags

Repository files navigation

Pipefy Developers — Where developers orchestrate intelligence

CI Status Python 3.11+ uv package manager MCP Server License

pipefy-labs

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 • Installation • Repository layout • MCP server • CLI • Agent skills • Documentation • Development • Contributing

Overview

Component Package / path Purpose
MCP server pipefy-mcp-server Exposes 149 tools to MCP clients (Cursor, Claude Desktop, Claude Code, and others).
CLI pipefy-cli Terminal commands aligned with MCP capabilities; see docs/parity.md.
SDK pipefy-sdk Vendor GraphQL client, services, and models shared by MCP and CLI.
Skills skills/ Markdown playbooks (Anthropic Skills format) for common Pipefy workflows.

Feedback and issues: GitHub Issues · dev@pipefy.com

Installation

Pre-1.0 ships from this git repo via uvx and uv tool install. PyPI becomes the canonical source at v1.0. The current beta line is v0.2.0-beta.* (first tag: v0.2.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.

The CLI snippets below pin @latest, a moving git tag the release flow updates to point at the most recent release. To pin a specific version, swap @latest for a version tag (e.g. @v0.2.0-beta.2). The --with pipefy-sdk @ ...#subdirectory=packages/sdk / pipefy-auth @ ...#subdirectory=packages/auth flags are required pre-1.0: this repo is a uv workspace, and the workspace members are not yet published to PyPI, so uv needs them named explicitly. The flags go away at v1.0 (PyPI install).

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: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.

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:login

/plugin install pipefy registers the MCP server and the /pipefy:install + /pipefy:login slash commands. /pipefy:install runs uv tool install once to put pipefy on PATH (idempotent). /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 \
  --with "pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
  pipefy-cli --help

Permanent install:

uv tool install \
  --with "pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/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-sdk is the vendor GraphQL layer; MCP and CLI depend on it and do not import each other.

Path Distribution Role
packages/sdk/ pipefy-sdk GraphQL transport, services, queries, Pydantic models. Package README
packages/mcp/ pipefy-mcp-server MCP tool registration and server lifecycle. Package README
packages/cli/ pipefy-cli Typer CLI (pipefy command). Package README
skills/ — Agent skill playbooks. Catalog

MCP server

The server registers 149 tools across ten 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.

Domain Tools Summary Reference
Pipes & cards 37 Pipes, phases, fields, labels, cards, field conditions, attachments. docs
Database tables 17 Tables, records, schema, table-record attachments. docs
Relations 8 Pipe and card relations. docs
Reports 17 Pipe and organization reports, async exports. docs
Automations & AI 22 Automations, AI automations, AI agents, validators. docs
Observability 10 Logs, usage, credits, job exports. docs
Members, email & webhooks 11 Membership, inbox email, webhooks. docs
Organization 1 Organization metadata. docs
Portals 20 Portal read/CRUD, pages, elements, sub-portals (publish/unpublish). docs
Introspection 5 Schema discovery and raw GraphQL. docs

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.

Documentation

Document Description
docs/README.md Index by surface (MCP, CLI, SDK).
docs/config.md PIPEFY_* environment variables, config.toml schema and path, precedence chain.
docs/parity.md MCP tool ↔ CLI command matrix.
docs/MIGRATION.md Notes for existing MCP users.
AGENTS.md Repository guidelines for contributors and agents.
RELEASE.md Versioning and release process.

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.

Contributing

Contributions are welcome via issues and pull requests.

Area How to contribute
Skills Markdown only — see CONTRIBUTING.md.
MCP / CLI / SDK Follow AGENTS.md and docs/parity.md.
Field mapping gaps Open an issue with the field type and expected behavior.
Existing MCP setups docs/MIGRATION.md — configuration remains compatible.

About

MCP server, CLI, and agent skills for Pipefy.

Topics

cli sdk skills pipefy ai-toolkit mcp-server

Resources

Readme

Contributing

Contributing
Activity
Custom properties

Stars

25 stars

Watchers

1 watching

Forks

8 forks
Report repository

Releases 5

v0.2.0-beta.3 Latest
Jun 3, 2026
+ 4 releases

Packages

 
 
 

Contributors

Languages