Pipefy MCP Server

MCP (Model Context Protocol) server for integrating Pipefy GraphQL API with LLMs.

Overview

This MCP server enables LLMs to interact with Pipefy through comprehensive tools for managing pipes, cards, database tables, and records.

Features

Pipes & Cards

• pipefy_list_pipes - List available pipes and organizations
• pipefy_get_pipe - Get detailed pipe information (phases, members, fields, labels)
• pipefy_list_cards - List cards in a pipe with optional search
• pipefy_get_card - Get comprehensive card details with all field values
• pipefy_search_cards - Search cards by specific field values
• pipefy_create_card - Create a new card in a pipe
• pipefy_get_phase - Get phase details and fields

Database Tables & Records

• pipefy_list_tables - List database tables in an organization
• pipefy_get_table - Get detailed table information (fields, members, webhooks)
• pipefy_create_table - Create a new database table
• pipefy_list_table_records - List records from a table
• pipefy_get_table_record - Get comprehensive record details with all field values
• pipefy_create_table_record - Create a new record in a table

All tools support both Markdown (human-readable) and JSON (machine-readable) output formats.

Installation

# Install dependencies using uv
uv sync

# Or with pip
pip install -e .

Configuration

Set your Pipefy API token as an environment variable:

export PIPEFY_API_TOKEN=your_api_token_here

To get your API token:

1. Go to Pipefy Settings
2. Navigate to Personal Access Tokens
3. Create a new token with appropriate permissions

Usage

Running the Server

# Run with stdio transport (default)
python main.py

# Or if installed as a script
pipefy-mcp

Testing with MCP Inspector

PIPEFY_API_TOKEN=your_token npx @modelcontextprotocol/inspector python main.py

Cursor IDE Integration

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "pipefy": {
      "command": "python",
      "args": ["/path/to/pipefy-mcp/main.py"],
      "env": {
        "PIPEFY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Example Queries

Once connected, you can ask the LLM things like:

Pipes & Cards

• "List all cards in pipe 301234567"
• "Get details for card 123456789"
• "Search for cards with email john@example.com in pipe 301234567"
• "Show me the phases in pipe 301234567"
• "Create a new card in pipe 301234567 with title 'New Request'"

Database Tables & Records

• "List all database tables in organization 12345"
• "Show me the structure of table ZtEdWh"
• "Create a new table called 'Customers' in organization 12345"
• "List all records from table ZtEdWh"
• "Get details for record 987654"
• "Add a new customer record to table ZtEdWh"

API Reference

pipefy_get_pipe

Get detailed information about a Pipefy pipe.

Parameters:

• pipe_id (required): The unique ID of the pipe
• response_format: "markdown" (default) or "json"

pipefy_list_cards

List cards from a specific pipe.

Parameters:

• pipe_id (required): The pipe ID to list cards from
• limit: Maximum cards to return (1-50, default: 20)
• search: Optional search term for card titles
• response_format: "markdown" (default) or "json"

pipefy_get_card

Get detailed information about a specific card.

Parameters:

• card_id (required): The unique ID of the card
• response_format: "markdown" (default) or "json"

pipefy_search_cards

Search cards by a specific field value.

Parameters:

• pipe_id (required): The pipe ID to search in
• field_id (required): The field ID to search by
• field_value (required): The value to search for
• limit: Maximum cards to return (1-50, default: 20)
• response_format: "markdown" (default) or "json"

pipefy_get_phase

Get phase details and fields.

Parameters:

• phase_id (required): The unique ID of the phase
• response_format: "markdown" (default) or "json"

pipefy_list_pipes

List Pipefy pipes available to the user.

Parameters:

• organization_id: Optional organization ID to filter by
• response_format: "markdown" (default) or "json"

pipefy_create_card

Create a new card in a specific pipe.

Parameters:

• pipe_id (required): The pipe ID
• fields (required): List of field objects with field_id and field_value
• title: Optional card title
• response_format: "markdown" (default) or "json"

Database Tables API

pipefy_list_tables

List database tables from a specific organization.

Parameters:

• organization_id (required): The organization ID to list tables from
• response_format: "markdown" (default) or "json"

pipefy_get_table

Get detailed information about a specific database table.

Parameters:

• table_id (required): The alphanumeric ID of the table (e.g., 'ZtEdWh')
• response_format: "markdown" (default) or "json"

Returns: Table details including fields, members, webhooks, and record count.

pipefy_create_table

Create a new database table in an organization.

Parameters:

• organization_id (required): The organization ID where the table will be created
• name (required): The name for the new table
• color: Optional color for the table (e.g., 'blue', 'red', 'green', 'lime', 'yellow')
• response_format: "markdown" (default) or "json"

Returns: Details of the created table including its ID.

Table Records API

pipefy_list_table_records

List records from a database table.

Parameters:

• table_id (required): The alphanumeric ID of the table
• limit: Maximum records to return (1-50, default: 20)
• response_format: "markdown" (default) or "json"

pipefy_get_table_record

Get detailed information about a specific table record.

Parameters:

• record_id (required): The numeric ID of the record
• response_format: "markdown" (default) or "json"

Returns: Comprehensive record details with all field values.

pipefy_create_table_record

Create a new record in a database table.

Parameters:

• table_id (required): The alphanumeric ID of the table
• title (required): The title for the new record
• fields: List of field objects with field_id and field_value
• response_format: "markdown" (default) or "json"

Returns: Details of the created record including its ID.

Development

Project Structure

pipefy-mcp/
├── main.py              # Main server with all tools
├── pyproject.toml       # Project configuration
├── README.md            # This file
└── .cursor/skills/      # MCP builder skill reference

Adding New Tools

Follow the pattern in main.py:

1. Define a Pydantic model for input validation
2. Use @mcp.tool decorator with proper annotations
3. Include comprehensive docstrings
4. Implement error handling with _handle_api_error
5. Support both response formats