Temporal MCP Server

A Model Context Protocol (MCP) server that lets AI assistants observe and manage Temporal workflows. Built in Kotlin/JVM with a Node.js bridge for fast MCP initialization.

Prerequisites

JDK 17+
Node.js (for the MCP bridge)
Access to a Temporal server (local or Temporal Cloud)

Build

./gradlew shadowJar

The JAR is created at build/libs/temporal-mcp-server-1.0-SNAPSHOT.jar.

Configuration

The server is launched via minimal-mcp.js, which handles MCP protocol initialization and spawns the Java process.

MCP Client Configuration

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": [
        "path/to/minimal-mcp.js",
        "--namespace", "my-namespace",
        "--address", "my-host:7233"
      ],
      "env": {
        "TEMPORAL_API_KEY": "your-api-key"
      }
    }
  }
}

Command-Line Arguments

| Argument | Required | Description | |---|---|---| | --namespace | Yes | Temporal namespace | | --address | Yes | Temporal server address (e.g., my-ns.abc.tmprl.cloud:7233) |

Environment Variables

| Variable | Description | |---|---| | TEMPORAL_API_KEY | API key for Temporal Cloud authentication | | TEMPORAL_CLIENT_CERT_PATH | Path to mTLS client certificate file | | TEMPORAL_CLIENT_KEY_PATH | Path to mTLS client key file | | TEMPORAL_CLIENT_CERT | mTLS client certificate content (alternative to path) | | TEMPORAL_CLIENT_KEY | mTLS client key content (alternative to path) |

Authentication

API Key (Temporal Cloud)

Set TEMPORAL_API_KEY in the env section of your MCP config. The key is sent as a Bearer token in gRPC metadata.

mTLS Certificates

For mTLS authentication, provide either file paths or content directly:

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["path/to/minimal-mcp.js", "--namespace", "my-ns", "--address", "my-host:7233"],
      "env": {
        "TEMPORAL_CLIENT_CERT_PATH": "/path/to/client.pem",
        "TEMPORAL_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Tools

Workflow Observation

| Tool | Description | |---|---| | list_workflows | Lists workflows in the namespace. Supports query filter and pageSize (1-1000, default 10). | | get_workflow_status | Gets status of a specific workflow by workflowId (optional runId). Returns parentWorkflowId, parentRunId, taskQueue, closeTime, memo, and searchAttributes. | | get_workflow_history | Retrieves the complete event history of a workflow with full event attributes. | | query_workflow | Executes a query on a running workflow (workflowId, queryType, optional args). |

Workflow Actions

| Tool | Description | |---|---| | start_workflow | Starts a new workflow (workflowId, workflowType, taskQueue, optional args). | | send_signal | Sends a signal to a running workflow (workflowId, signalName, optional signalArgs). | | reset_workflow | Resets a workflow to a specific point in its history, creating a new run. Supports eventId or resetType: "last_workflow_task" to auto-detect the last WorkflowTaskCompleted event. | | terminate_workflow | Terminates a running workflow (workflowId, optional reason). |

Utilities

| Tool | Description | |---|---| | wait_for_activity | Polls until a workflow reaches a specific activity (workflowId, activityName, optional timeoutSeconds 1-3600). | | send_webhook | Sends an HTTP POST webhook (webhookUrl, payload, optional headers). Useful for completing async activities. |

Development

Running Tests

./gradlew test

Architecture

minimal-mcp.js acts as a bridge: it responds immediately to the MCP initialize handshake, then spawns the Java process in the background. Once Java is ready, all subsequent requests are forwarded to it.

temporal-mcp-server