Skip to main content
Glama
enzomotta

temporal-mcp-server

by enzomotta
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

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)

Related MCP server: n8n Manager for AI Agents

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers