# 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
```bash
# Install dependencies using uv
uv sync
# Or with pip
pip install -e .
```
## Configuration
Set your Pipefy API token as an environment variable:
```bash
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
```bash
# Run with stdio transport (default)
python main.py
# Or if installed as a script
pipefy-mcp
```
### Testing with MCP Inspector
```bash
PIPEFY_API_TOKEN=your_token npx @modelcontextprotocol/inspector python main.py
```
### Cursor IDE Integration
Add to your `.cursor/mcp.json`:
```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
