Temporal MCP

Temporal MCP

An MCP server that gives AI agents read-only access to your Temporal infrastructure — plus an Agent Skill that provides expert Temporal development guidance.

The server exposes 28 tools across six categories—workflows, schedules, infrastructure, workers, connections, and documentation—along with 5 resource types, 4 prompt templates, a built-in documentation search subsystem, and a policy engine that controls what agents are allowed to see. Temporal operations are read-only (no writes to Temporal state). The docs.refresh tool does have local side effects: it performs network git syncs and writes cache/index files under ~/.temporal-mcp.

Agent Skill

temporal-mcp ships a spec-compliant Agent Skill at skill/SKILL.md. The skill is a curated knowledge package — markdown reference files covering Temporal architecture, determinism rules, workflow patterns, common gotchas, versioning strategies, troubleshooting decision trees, and language-specific guidance for TypeScript, Python, and Go.

The skill and the MCP server solve complementary problems:

• The skill teaches agents how to write correct Temporal code
• The MCP server lets agents observe running infrastructure

Install the skill standalone (no MCP server required):

# Claude Code / Claude Desktop (skills directory)
cp -r skill/ ~/.claude/skills/temporal-mcp/

Or use it via the MCP server — the skill is included in the package. When both are active, tools like temporal.workflow.describe return a guidance field pointing to the relevant reference file when the workflow is in a notable state (failed, timed out, etc.), and docs.search searches both the Temporal docs corpus and the curated references.

Features

• 28 read-only tools for inspecting workflows, schedules, task queues, namespaces, workers, and cluster state
• 5 MCP resource types for direct access to Temporal entities via URI templates
• 4 prompt templates (temporal-debug-workflow, temporal-triage, temporal-docs-answer, temporal-safe-mutation) that combine live cluster data with curated guidance
• Agent Skill at skill/SKILL.md with 22 curated reference files for TypeScript, Python, and Go development
• Documentation subsystem that indexes and searches the Temporal docs corpus plus curated references locally
• Multi-profile connections to multiple Temporal clusters (self-hosted and Cloud) from one server
• Policy engine with four modes, glob-based tool filtering, and profile/namespace allowlists
• Audit logging with structured JSON to stderr and automatic sensitive field redaction
• Zero Temporal write operations by design—no starts, signals, cancels, terminates, or deletes

Using Both Together

When the MCP server is connected to a Temporal cluster and the skill is loaded into the agent's context, the two capabilities reinforce each other:

• temporal.workflow.describe on a timed-out or failed workflow returns a guidance field: "See skill/references/core/gotchas.md for common timeout causes...". The agent can then load that reference file to understand the failure and how to fix the code.
• temporal.workflow.history.summarize detecting workflow task failures (often non-determinism errors) returns guidance pointing to skill/references/core/determinism.md and skill/references/core/versioning.md.
• docs.search searches both the Temporal documentation corpus and the curated reference files, with curated results ranked higher (they're more information-dense).
• docs.get can retrieve curated reference files directly: docs.get({ sourcePath: "skill/references/core/determinism.md" }).
• Prompt templates (temporal-debug-workflow, temporal-triage) orchestrate multi-step diagnostic workflows that interleave MCP tool calls with curated knowledge lookups.

Prerequisites

• Node.js 20+ runtime
• A running Temporal cluster (self-hosted) or a Temporal Cloud account
• An MCP-compatible client (Claude Desktop, Claude Code, or any client that speaks stdio transport)

Installation

npx -y temporal-mcp

For local development builds:

bun install
bun run build
node dist/cli.js

The server communicates over stdio transport by default. Your MCP client launches it as a subprocess—you don't run it in a separate terminal.

Bun is required for development and build workflows. Runtime execution uses Node.js (dist/cli.js or the temporal-mcp CLI).

Configuration

The server looks for configuration in this order, using the first file it finds:

1. The path in the TEMPORAL_MCP_CONFIG environment variable
2. .temporal-mcp.json in the current working directory
3. ~/.config/temporal-mcp/config.json
4. Built-in defaults (no profiles configured)

Self-hosted profile

{
  "temporal": {
    "defaultProfile": "local",
    "profiles": {
      "local": {
        "kind": "self-hosted",
        "address": "localhost:7233",
        "namespace": "default"
      }
    }
  }
}

Cloud profile

{
  "temporal": {
    "defaultProfile": "production",
    "profiles": {
      "production": {
        "kind": "cloud",
        "address": "my-namespace.tmprl.cloud:7233",
        "namespace": "my-namespace"
      }
    }
  }
}

For Cloud connections, set the TEMPORAL_API_KEY environment variable with your API key.

Multiple profiles

{
  "temporal": {
    "defaultProfile": "local",
    "profiles": {
      "local": {
        "kind": "self-hosted",
        "address": "localhost:7233",
        "namespace": "default"
      },
      "production": {
        "kind": "cloud",
        "address": "my-namespace.tmprl.cloud:7233",
        "namespace": "my-namespace"
      }
    }
  }
}

Every tool accepts an optional profile parameter. When omitted, the server uses defaultProfile. When provided, it connects to that specific profile's cluster.

Connecting to an MCP client

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "temporal": {
      "command": "npx",
      "args": ["-y", "temporal-mcp"]
    }
  }
}

Claude Code

claude mcp add temporal -- npx -y temporal-mcp

Other clients

Any MCP client that supports stdio transport can launch the server. Point it at npx -y temporal-mcp (or temporal-mcp after a global install) and the server handles the rest.

Tools

Workflow

Schedule

Infrastructure

Worker

Connection

Documentation

docs.search boosts curated reference results 1.5× over raw docs corpus results. docs.get accepts paths in the form skill/references/{category}/{file}.md to retrieve curated reference files directly.

Prompts

Four prompt templates are registered and discoverable by any MCP client that supports the prompts capability:

Each prompt instructs the agent to call the relevant MCP tools, load the appropriate curated reference files, and produce a structured output. They're designed to be used directly from any MCP client prompt picker.

Resources

Policy engine

The policy engine controls which tools an agent can invoke. It defaults to readOnly, which allows all 28 tools since they are all read-only by design.

Modes

Tool filtering

In any mode, allowPatterns and denyPatterns can control which tools are available:

{
  "policy": {
    "mode": "custom",
    "allowPatterns": ["temporal.workflow.*", "temporal.schedule.*"],
    "denyPatterns": ["temporal.worker.**"]
  }
}

Deny patterns take precedence over allow patterns.

Profile and namespace allowlists

Restrict which profiles and namespaces agents can access. An empty list means "allow all":

{
  "policy": {
    "allowedProfiles": ["local", "staging"],
    "allowedNamespaces": ["default", "my-app"]
  }
}

Hard read-only lock

Setting hardReadOnly to true overrides every other policy setting and locks the server to read-only tools, regardless of the configured mode:

{
  "policy": {
    "hardReadOnly": true
  }
}

Break-glass override

The unsafe mode requires the TEMPORAL_MCP_BREAK_GLASS environment variable to be set. Without it, unsafe tool calls are denied with BREAK_GLASS_REQUIRED. This exists as a deliberate speed bump—you have to opt in twice.

Safety

Audit logging

Every tool invocation is logged as structured JSON to stderr, including the tool name, parameters, policy decision, result status, and duration. Each request gets a unique tracking ID.

Sensitive field redaction

Tool responses and JSON resource responses are automatically scanned for sensitive fields. Any key matching one of these patterns (case-insensitive) has its value replaced with [REDACTED]:

apiKey, password, token, secret, credential, authorization, cookie, session

What this server does not do

This server is intentionally limited to observation. It does not:

• Start, signal, cancel, or terminate workflows
• Create, pause, unpause, or delete schedules
• Create or modify namespaces
• Modify task queue configuration
• Perform any cluster administration
• Write to any Temporal state

Project structure

src/
  index.ts                  # Entry point
skill/
  SKILL.md                  # Agent Skills spec entry point
  references/
    core/                   # Language-agnostic reference files (determinism, patterns, etc.)
    typescript/             # TypeScript SDK reference files
    python/                 # Python SDK reference files
    go/                     # Go SDK reference files
packages/
  server/                   # MCP server, config, policy, tools, resources, safety
    src/
      guidance/             # Guidance annotation patterns and post-processing
      prompts/              # MCP prompt template registration
  temporal/                 # Temporal client, gRPC calls, capability matrix
  docs/                     # Documentation indexing and search (corpus + curated refs)

Maintainer release workflow

One-time bootstrap publish

1. Authenticate to npm from a maintainer machine (npm login).
2. Build and validate:

bun install --frozen-lockfile
bun run check
bun run build
npm pack --dry-run

3. Publish the initial package:

npm publish --access public

4. In npm package settings, add trusted publishing for this repository and .github/workflows/release.yml.Provenance is generated automatically in the tag-driven CI release workflow once OIDC trusted publishing is configured.

Ongoing releases (tag-driven)

1. Bump the package version and create a vX.Y.Z tag:

bun run release:patch
# or: bun run release:minor
# or: bun run release:major

2. Pushing the tag triggers .github/workflows/release.yml, which:
   • installs dependencies with Bun
   • runs bun run check and bun run build
   • publishes to npm using OIDC trusted publishing (no NPM_TOKEN secret)

Development

bun install
bun run check
# optional coverage report
bun run test:coverage

For pull request validation expectations and CI parity details, see CONTRIBUTING.md.