temporal-mcp

Temporal MCP Server

An MCP (Model Context Protocol) server for debugging Temporal workflows. This server enables LLM-assisted debugging by exposing Temporal workflow inspection tools.

Features

• list_workflows - List workflow executions with optional query filter
• describe_workflow - Get detailed info about a specific workflow
• get_workflow_history - Fetch event history for debugging

Requirements

• Python 3.11+
• uv for dependency management
• A running Temporal server (local or cloud)

Installation

# Clone the repository
git clone <repo-url>
cd temporal-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Configuration

Set environment variables to configure the Temporal connection:

| Variable | Description | Default | |----------|-------------|---------| | TEMPORAL_ADDRESS | Temporal server address | localhost:7233 | | TEMPORAL_NAMESPACE | Temporal namespace | default | | TEMPORAL_TLS_CERT | Path to TLS certificate (for Cloud) | - | | TEMPORAL_TLS_KEY | Path to TLS key (for Cloud) | - | | TEMPORAL_API_KEY | API key (for Cloud) | - |

Docker

Connect to Temporal Server

If you have Temporal running (locally or remotely):

# Connect to Temporal on host machine
docker compose up

# Or specify a custom address
TEMPORAL_ADDRESS=my-temporal:7233 docker compose up

Connect to Temporal Cloud

For Temporal Cloud with mTLS certificates:

# Place your certificates in a certs/ directory, then:
docker compose up
# After uncommenting the TLS environment variables in docker-compose.yml

Or with API key:

TEMPORAL_ADDRESS=your-ns.tmprl.cloud:7233 \
TEMPORAL_NAMESPACE=your-ns \
TEMPORAL_API_KEY=your-key \
docker compose up

Local Development (without Docker)

Install and run directly with Python:

For Temporal Cloud, set the appropriate environment variables:

export TEMPORAL_ADDRESS="your-namespace.tmprl.cloud:7233"
export TEMPORAL_NAMESPACE="your-namespace"
export TEMPORAL_API_KEY="your-api-key"

Or with TLS certificates:

export TEMPORAL_ADDRESS="your-namespace.tmprl.cloud:7233"
export TEMPORAL_NAMESPACE="your-namespace"
export TEMPORAL_TLS_CERT="/path/to/cert.pem"
export TEMPORAL_TLS_KEY="/path/to/key.pem"

Usage

With Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "temporal": {
      "command": "uv",
      "args": ["run", "temporal-mcp"],
      "cwd": "/path/to/temporal-mcp",
      "env": {
        "TEMPORAL_ADDRESS": "localhost:7233",
        "TEMPORAL_NAMESPACE": "default"
      }
    }
  }
}

Standalone

temporal-mcp

Available Tools

list_workflows

List workflow executions with optional filtering.

list_workflows(query="", limit=10)

• query: Optional Temporal list filter syntax (e.g., WorkflowType="MyWorkflow" AND ExecutionStatus="Running")
• limit: Maximum workflows to return (default 10, max 100)

describe_workflow

Get detailed information about a specific workflow.

describe_workflow(workflow_id, run_id="")

• workflow_id: The workflow ID to describe
• run_id: Optional run ID (uses latest if not specified)

get_workflow_history

Fetch the event history for a workflow execution.

get_workflow_history(workflow_id, run_id="", max_events=100)

• workflow_id: The workflow ID
• run_id: Optional run ID (uses latest if not specified)
• max_events: Maximum events to return (default 100, max 1000)

Development

Setup

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Commands

# Format code
black src tests

# Lint
ruff check src tests

# Type check
mypy src

# Run tests
pytest

# Run all checks
black src tests && ruff check src tests && mypy src && pytest

Project Structure

temporal-mcp/
├── pyproject.toml          # Project config and dependencies
├── Dockerfile
├── docker-compose.yml       # Docker setup for MCP server
├── README.md
├── src/temporal_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP server and tool definitions
│   ├── client.py           # Temporal client wrapper
│   ├── config.py           # Environment-based configuration
│   └── models.py           # Pydantic models
├── tests/
│   ├── conftest.py         # Test fixtures
│   ├── test_config.py
│   ├── test_client.py
│   └── test_server.py
└── docs/
    └── PLAN.txt

License

MIT