# 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