# 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]"

# Connect to Temporal on host machine
docker compose up

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

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

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

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

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"

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

temporal-mcp

list_workflows(query="", limit=10)

describe_workflow(workflow_id, run_id="")

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

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

# 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

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