Alteryx MCP

An MCP server that exposes comprehensive Alteryx workflow manipulation tools over stdio, enabling AI assistants to:

• Read & Analyze: Summarize workflows into Markdown (containers, connections, SQL, diagrams)
• Find Tools: Search for tools by ID, type, or annotation patterns
• Edit Configurations: Modify tool settings, field selections, annotations
• Update SQL: Change database queries with OCI compliance (auto-removes -- comments)
• Manage Connections: Update DCM connection identifiers
• Create Workflows: Build new .yxmd files programmatically

It wraps alteryx_mcp/alteryx_mcp.py from this repository.

Demo

Watch the demo video

Features

1. Workflow Analysis

• Parse and summarize entire workflows
• Extract container hierarchies, tool types, database connections
• Generate Mermaid diagrams for data flow visualization

2. Tool Discovery

• Find tools by ToolID, plugin type (e.g., AlteryxSelect, DbFileInput)
• NEW: find_tools_fast() - Optimized regex-based search (10-100x faster for specific ToolID lookups)
• Search by annotation text patterns
• Get complete tool configuration details

3. Direct Editing

• Select Tools: Update field selections (selected: true/false) and rename fields
• Annotations: Change tool annotations/labels
• SQL Queries: Update DbFileInput queries with automatic comment removal for OCI
• Connections: Swap DCM connection IDs across tools
• NEW: Row Limits: Get, update, and batch-modify row limits for Sample/Filter tools
• All edits support dry-run mode for safe previewing

4. Connection Management

• Batch Update Connections: Update multiple tools with the same connection ID
• Copy connection from reference tool or use provided connection ID
• Update entire workflow at once

5. Row Limit Management (NEW)

• Get Row Limits: Read current First N, Last N, Sample N settings
• Update Single Tool: Change row limit for specific tool
• Batch Update: Mass-modify row limits across entire workflow
• Update by specific tool IDs or by plugin type (e.g., all Sample tools)

6. Workflow Creation

• Build workflows from scratch with JSON configuration
• Define tools, positions, connections programmatically
• Specify custom metadata

Install (editable dev)

# From repo root
pip install -e .

Run (stdio)

alteryx-mcp

Tools Reference

Analysis Tools

summarize_workflow

summarize_workflow(
    workflow: str,           # Path to .yxmd file
    mapping: str | None      # Optional JSON mapping for connection aliases
) -> str                     # Returns Markdown summary

Example:

{
  "workflow": "c:/projects/VCI/VCIProjectionBaseLine.yxmd",
  "mapping": "c:/projects/connections.json"
}

Returns comprehensive Markdown with:

• Metadata (WorkflowId, Description)
• Container hierarchy
• Top tool types
• Database connections with queries
• Output destinations
• Mermaid flowcharts

---

find_tools

find_tools(
    workflow: str,                    # Path to .yxmd file
    tool_id: int | None = None,       # Find specific tool ID
    plugin_type: str | None = None,   # e.g., 'AlteryxSelect', 'DbFileInput'
    annotation_pattern: str | None = None  # Search in annotations
) -> str                              # Returns JSON with matching tools

Examples:

// Find all Select tools
{
  "workflow": "path/to/workflow.yxmd",
  "plugin_type": "AlteryxSelect"
}

// Find tools mentioning "v12Live" in annotations
{
  "workflow": "path/to/workflow.yxmd",
  "annotation_pattern": "v12Live"
}

// Find specific tool
{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 375
}

Supported plugin types:

• AlteryxSelect, DbFileInput, DbFileOutput
• Filter, Join, Sort, Formula
• Browse, TextBox, ToolContainer
• Union, Summarize, Sample, Unique
• RecordID, MultiRowFormula, TextInput, DateTimeInput

---

Editing Tools

update_select_tool

update_select_tool(
    workflow: str,          # Path to .yxmd file
    tool_id: int,          # Tool ID of Select tool
    field_updates: str,    # JSON string with field updates
    dry_run: bool = False
) -> str                   # Status message

Example - Update field selections:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 375,
  "field_updates": "{\"SCM37_CTRA22_IBCONO\": {\"selected\": false}, \"SCM37_CTRA22_IBFACI\": {\"selected\": true, \"rename\": \"FACILITY_CODE\"}}",
  "dry_run": true
}

Field update options:

• selected: true or false
• rename: New field name

---

update_annotation

update_annotation(
    workflow: str,          # Path to .yxmd file
    tool_id: int,          # Tool ID to update
    new_annotation: str,   # New annotation text
    dry_run: bool = False
) -> str

Example:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 12,
  "new_annotation": "dcm:prod-oracle\nQuery=SELECT * FROM MPHEAD WHERE CONO=1",
  "dry_run": false
}

---

update_sql_query

update_sql_query(
    workflow: str,                  # Path to .yxmd file
    tool_id: int,                  # Tool ID of DbFileInput
    new_query: str,                # New SQL query
    remove_comments: bool = True,  # Strip -- comments for OCI
    dry_run: bool = False
) -> str

Example - Update query with OCI compliance:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 12,
  "new_query": "SELECT IACONO, IAPUNO, IACUCD -- Company info\nFROM MVXCDTA.MPHEAD\nWHERE IACONO = 1",
  "remove_comments": true,
  "dry_run": false
}

Result (after comment removal):

SELECT IACONO, IAPUNO, IACUCD
FROM MVXCDTA.MPHEAD
WHERE IACONO = 1

---

update_connection_id

update_connection_id(
    workflow: str,              # Path to .yxmd file
    tool_id: int,              # Tool ID to update
    new_connection_id: str,    # New DCM connection ID (UUID)
    dry_run: bool = False
) -> str

Example:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 12,
  "new_connection_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dry_run": false
}

---

batch_update_connections

batch_update_connections(
    workflow: str,
    tool_ids: List[int],
    source_connection_id: str | None = None,
    source_tool_id: int | None = None,
    dry_run: bool = False
) -> str

Example:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_ids": [12, 14, 16],
  "source_tool_id": 13,
  "dry_run": true
}

---

rewrite_connections

rewrite_connections(
    workflow: str,     # Path to .yxmd file
    config: str,       # Path to JSON config
    dry_run: bool = False
) -> str

Config JSON format:

{
  "connections": {
    "old-uuid-1": {
      "new_id": "new-uuid-1",
      "old_label": "dev-db",
      "new_label": "prod-db"
    }
  }
}

---

Row Limit Tools

get_row_limit

get_row_limit(
    workflow: str,
    tool_id: int
) -> str

Example:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 10
}

update_row_limit

update_row_limit(
    workflow: str,
    tool_id: int,
    first_n: int | None = None,
    last_n: int | None = None,
    sample_n: int | None = None,
    dry_run: bool = False
) -> str

Example:

{
  "workflow": "path/to/workflow.yxmd",
  "tool_id": 10,
  "first_n": 500,
  "dry_run": false
}

batch_update_row_limits

batch_update_row_limits(
    workflow: str,
    tool_ids: List[int] | None = None,
    plugin_type: str | None = None,
    first_n: int | None = None,
    last_n: int | None = None,
    sample_n: int | None = None,
    dry_run: bool = False
) -> str

Example:

{
  "workflow": "path/to/workflow.yxmd",
  "plugin_type": "Sample",
  "first_n": 1000,
  "dry_run": false
}

---

Creation Tools

create_workflow

create_workflow(
    output_path: str,        # Where to save .yxmd
    tools_config: str,       # JSON array of tool configs
    connections: str | None, # Optional JSON array of connections
    metadata: str | None     # Optional JSON dict of metadata
) -> str

Example - Create simple workflow:

{
  "output_path": "c:/temp/new_workflow.yxmd",
  "tools_config": "[{\"tool_id\": 1, \"plugin\": \"TextInput\", \"position\": {\"x\": 100, \"y\": 100}, \"configuration\": {\"Text\": \"Hello World\"}, \"annotation\": \"Data source\"}, {\"tool_id\": 2, \"plugin\": \"Browse\", \"position\": {\"x\": 300, \"y\": 100}, \"annotation\": \"View output\"}]",
  "connections": "[{\"origin\": 1, \"destination\": 2}]",
  "metadata": "{\"Name\": \"My Workflow\", \"Description\": \"Auto-generated test workflow\"}"
}

Tool configuration structure:

{
  tool_id?: number,           // Optional, defaults to index
  plugin: string,             // Plugin type name
  position: {x: number, y: number},
  configuration: object,      // Tool-specific config
  annotation?: string         // Optional annotation
}

Connection structure:

{
  origin: number,                      // Source tool ID
  destination: number,                 // Target tool ID
  origin_connection?: string,          // Default: "Output"
  destination_connection?: string      // Default: "Input"
}

---

MCP Client Configuration

Point your MCP client (e.g., GitHub Copilot, Claude Desktop) to launch the script on stdio:

{
  "mcpServers": {
    "alteryx": {
      "command": "alteryx-mcp",
      "args": []
    }
  }
}

Or with full path:

{
  "mcpServers": {
    "alteryx": {
      "command": "python",
      "args": ["-m", "alteryx_mcp.server"]
    }
  }
}

---

Usage Patterns

Pattern 1: Find and Update Field Selections

1. User: "Find all Select tools in the workflow"
   → find_tools(workflow="...", plugin_type="AlteryxSelect")

2. User: "In tool 375, deselect field IBCONO and rename IBFACI to FACILITY"
   → update_select_tool(workflow="...", tool_id=375, 
                        field_updates='{"IBCONO": {"selected": false}, 
                                       "IBFACI": {"rename": "FACILITY"}}')

Pattern 2: Update SQL for OCI Compliance

1. User: "Show me all database input tools"
   → find_tools(workflow="...", plugin_type="DbFileInput")

2. User: "Update the SQL in tool 12 and remove all comments"
   → update_sql_query(workflow="...", tool_id=12, 
                      new_query="SELECT...", remove_comments=true)

Pattern 3: Change Annotations

1. User: "Find tools connected to v12Live"
   → find_tools(workflow="...", annotation_pattern="v12Live")

2. User: "Update annotation for tool 12 to show production connection"
   → update_annotation(workflow="...", tool_id=12, 
                       new_annotation="dcm:prod-oracle\\nQuery=...")

Pattern 4: Create New Workflow

User: "Create a workflow that reads from TextInput and shows Browse output"
→ create_workflow(output_path="...", 
                  tools_config='[{"plugin": "TextInput", ...}, 
                                 {"plugin": "Browse", ...}]',
                  connections='[{"origin": 1, "destination": 2}]')

---

Advanced Features

OCI Compliance

All SQL operations automatically handle Oracle Instant Client requirements:

• Removes -- style comments (not supported in OCI)
• Preserves multi-line queries
• Maintains query formatting

Dry Run Mode

All editing tools support dry_run=true to preview changes without writing to disk.

Pattern Matching

The MCP uses efficient XML pattern matching to locate tools:

• By Plugin type (partial match supported)
• By ToolID (exact match)
• By annotation text (case-insensitive substring)

Container Support

Tools within containers are fully supported:

• Search recurses into nested containers
• Container paths preserved in results
• Edits work on tools at any depth

---

Architecture

alteryx-mcp/
├── alteryx_mcp/
│   ├── server.py          # MCP FastMCP server exposing 8 tools
│   └── __init__.py
├── pyproject.toml         # Package metadata
└── README.md              # This file

The server is a thin wrapper around alteryx_mcp.py which provides:

• XML parsing and manipulation
• Tool configuration updates
• Workflow creation
• Safe file writing with proper encoding

---

Troubleshooting

Tool not found: Verify ToolID exists using find_tools()

SQL comments not removed: Ensure remove_comments=true is set

Workflow won't open in Alteryx: Check XML formatting; use dry_run first

Connection update failed: Verify UUID format for connection IDs

Field not updated: Check exact field name spelling (case-sensitive)

---

Contributing

This MCP server is part of the Alteryx MCP project. To extend:

1. Add new functions to alteryx_mcp/alteryx_mcp.py
2. Expose via @mcp.tool() decorators in server.py
3. Update this README with examples
4. Test with real workflows

---

License

Internal tool for Alteryx MCP project use.