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.