mcp-temporal-self-service

vengal-work/mcp-temporal-self-service

3.1

If you are the rightful owner of mcp-temporal-self-service and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

An MCP server that processes YAML requests to perform operations on Temporal namespaces.

MCP Temporal Self-Service

An MCP server that lets you create Temporal namespaces directly from an MCP-enabled client such as Perplexity.

Two main tools available:

  • Plan namespace → Show the exact temporal CLI command that will be run.
  • Create namespace → Run the command and create the namespace.

Both tools work with just a namespace name — no YAML or extra config required.

How it works

This MCP server wraps the Temporal CLI (temporal) and exposes it to your AI client. When you run Create namespace with name="orders-dev", it executes:

temporal operator namespace create \
  --namespace orders-dev \
  --retention 168h \
  --address 127.0.0.1:7233

By default, retention is 7 days and address is 127.0.0.1:7233 (Temporal dev server). You can override the address by setting the TEMPORAL_ADDRESS environment variable.

Folder structure

mcp-temporal-self-service/
├─ scripts/
│  ├─ run_dev.sh         # Start Temporal dev server
│  └─ run_mcp.sh         # Launch MCP server with correct CWD
├─ server/
│  ├─ tools/
│  │  ├─ __init__.py
│  │  └─ namespaces.py   # Implements namespace tools
│  ├─ __init__.py
│  ├─ main.py            # MCP entrypoint (tool registration)
│  └─ models.py          # Pydantic models
├─ README.md
└─ requirements.txt

Prerequisites

  • Python 3.11+ (3.12 is fine)
  • Temporal CLI (temporal) installed and on your PATH
  • Perplexity Mac app (or any MCP-enabled client)
  • macOS or Linux terminal

Local setup

git clone <your-repo-url>
cd mcp-temporal-self-service

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Start Temporal dev server

In a separate terminal:

temporal server start-dev
# UI: http://localhost:8233
# gRPC: 127.0.0.1:7233

Run the MCP server (local test)

From project root:

# Direct
python -m server.main

# OR via launcher script (recommended)
chmod +x scripts/run_mcp.sh
./scripts/run_mcp.sh

You should see it start without errors.

Perplexity MCP connector setup

  1. Open Perplexity → Settings → Connectors → Add Connector → Simple

  2. Name: temporal-self-service

  3. Command: (use absolute path)

    /ABS/PATH/TO/mcp-temporal-self-service/scripts/run_mcp.sh

  4. Env vars:

    • PYTHONUNBUFFERED=1
    • TEMPORAL_ADDRESS=127.0.0.1:7233
    • (optional if CLI not found) PATH=/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin

  5. Save, then enable the connector under Sources.

Usage in Perplexity

Plan namespace:

Use "Plan namespace" with name="orders-dev"

Create namespace:

Use "Create namespace" with name="orders-dev"

Optional extra fields:

  • description="Team Orders dev"
  • retention_days=10 (1–30 days, default 7)

Troubleshooting

context deadline exceeded

  • Ensure Temporal dev server is running: temporal operator cluster health --address 127.0.0.1:7233

temporal: command not found

  • Add the directory containing temporal to your PATH in connector env, or
  • Replace "temporal" in server/tools/namespaces.py with the full path from which temporal.

ModuleNotFoundError: server

  • Use scripts/run_mcp.sh so the working directory is correct.

Namespace already exists

  • Choose a new name and re-run.