Temporal MCP Server

A Model Context Protocol (MCP) server for Temporal Cloud that enables Claude Code to interact with your Temporal workflows across all regions.

🌍 Multi-Region Support

Access different Temporal Cloud regions:

• 🇺🇸 US (us-west-2)
• 🇪🇺 EU (eu-central-1)
• 🇦🇺 AU (ap-southeast-2)
• 🇮🇳 IN (ap-south-1)

🚀 Quick Setup

1. Configure Environment

Copy .env.example and setup the values

2. Add to Claude Code

Edit ~/.claude.json:

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["/absolute/path/to/your/temporal-mcp/build/index.js"],
      "env": {
        "TEMPORAL_API_KEY": "your-actual-api-key",
        "TEMPORAL_ACCOUNT_ID": "<cloud_account_id>",
        "DEFAULT_REGION": "us"
      }
    }
  }
}

3. Restart Claude Code

That's it! The server auto-connects to any region based on your queries.

🛠️ Available Tools

1. get_workflow_step_results ⭐ (Recommended)

Get processed step results with resultUri for downloading logs - use this instead of full history!

Use when: You want step summaries, resultUri, durations, or to debug flows Returns: Compact JSON with step names, resultUri, success status, durations

"Get step results for workflow 'refresh-monitors-456' run 'abc-123' in EU region"

Response:

{
  "success": true,
  "totalSteps": 3,
  "steps": [
    {
      "stepName": "fetchData",
      "isSuccess": true,
      "resultUri": "flowData/99/99999/flow-id/run-id/step-fetchData/1234567890.json",
      "durationSeconds": "2.45",
      "exposedData": { "count": 150 }
    }
  ]
}

2. list_workflow_executions

Query workflows with filters using Temporal visibility syntax.

{
  "query": "WorkflowType='refreshSlackUsersFlow' AND ExecutionStatus='Running'",
  "pageSize": 20,
  "region": "eu"
}

Example queries:

• "ExecutionStatus='Running'" - All running workflows
• "ExecutionStatus='Failed' AND StartTime > '2026-02-01T00:00:00Z'" - Recent failures
• "WorkflowType='refreshGithubUsersFlow'" - Specific workflow type

3. describe_workflow_execution

Get workflow status, timing, and metadata.

{
  "workflowId": "my-workflow-123",
  "region": "us"
}

4. terminate_workflow_execution

Stop a running workflow.

{
  "workflowId": "stuck-workflow",
  "reason": "Manual termination - investigating data source issue",
  "region": "au"
}

5. list_closed_workflow_executions

List workflows that completed in a time range.

{
  "startTime": "2026-02-01T00:00:00Z",
  "endTime": "2026-02-05T23:59:59Z",
  "region": "in"
}

6. get_workflow_execution_history

Get raw Temporal event history - only use if you need full history! Warning: Can be 80k+ characters. Use get_workflow_step_results instead.

💡 Usage Examples

Get Step Results with ResultUri (Most Common)

"Use temporal MCP and get step results for workflow 'intune.refreshIntuneEntitiesFlow.orgPk_756d...' run 'abc-123' and show me the resultUri for each step"

Debug Failed Flow

"Show me failed workflows in EU region from last 24 hours, then get step results for the most recent failure"

Monitor Specific Flow

"Is the GitHub user sync running for org 12345 in US region?"

Cross-Region Health Check

"Compare total running workflows across all regions"

Performance Analysis

"Get step results for the last 5 runs of 'refreshSlackUsersFlow' in US region and show me average step durations"

🌐 Region Handling

All tools accept an optional region parameter:

{ "region": "us" }  // United States (default)
{ "region": "eu" }  // Europe
{ "region": "au" }  // Australia
{ "region": "in" }  // India

Without region: Uses DEFAULT_REGION from config Natural language: Claude understands "EU region", "Australia", etc.

Automatic Mapping

The server automatically maps regions to endpoints No manual configuration needed!

🔧 Technical Details

What get_workflow_step_results Does

1. Fetches workflow history from Temporal
2. Filters for activity completed/failed events
3. Decodes base64 payloads → JSON
4. Extracts stepName, resultUri, exposedData
5. Calculates step durations
6. Deduplicates by step name
7. Returns compact summary

Connection Management

• Lazy-loads connections (only connects when needed)
• Maintains separate connection per region
• Reuses connections automatically
• First query to a region: ~1-2 seconds
• Subsequent queries: Fast (cached connection)

Event Types Processed

• Event Type 12: Activity Task Completed
• Event Type 13: Activity Task Failed
• Event Type 3: Workflow Execution Failed

🎯 Best Practices

✅ Do This

• Use get_workflow_step_results for most queries
• Specify region when known
• Use natural language with Claude
• Download logs via resultUri

❌ Avoid This

• Using get_workflow_execution_history unless needed
• Parsing raw history manually
• Forgetting to specify region for known workflows

📝 Common Patterns

Pattern 1: Debugging Failed Flows

1. "List failed flows from last hour in US region"
2. "Get step results for workflow XYZ run ABC"
3. Use resultUri to download logs
4. Analyze error from step data

Pattern 2: Performance Investigation

1. "Get step results for last 5 successful runs"
2. "Compare step durations"
3. "Identify slowest steps"

Pattern 3: Cross-Region Monitoring

1. "Query all regions for specific workflow type"
2. "Aggregate results by region"
3. "Identify regional differences"

🔍 Troubleshooting

"Can't find workflow"

→ Try searching other regions or verify workflow ID

"Connection error"

→ Check API key and account ID in config

"Response too large"

→ Use get_workflow_step_results instead of full history

"Region not working"

→ Verify region code is one of: us, eu, au, in

📚 Response Format

All responses include region information:

{
  "success": true,
  "region": "eu",
  "namespace": "your_temporal_host.<cloud_account_id>",
  "data": { ... }
}

Step results also include:

{
  "totalSteps": 3,
  "steps": [
    {
      "stepName": "...",
      "isSuccess": true,
      "resultUri": "...",
      "durationSeconds": "2.45",
      "exposedData": { ... }
    }
  ]
}

🚦 Getting Started

1. Add your API key to .env
2. Update Claude Code config with paths and credentials
3. Restart Claude Code
4. Test: "List workflows in US region"
5. Get step results: "Get step results for workflow X run Y"
6. Use resultUri to download logs

🎉 Quick Examples

Simple:

"List running workflows"

With region:

"Show failed workflows in EU from today"

Get step results:

"Get step results for workflow X run Y and show me resultUri"

Cross-region:

"Search all regions for workflow containing 'github'"

Performance:

"Compare execution times between US and EU regions"

---

Ready to use! Just add your API key and start debugging workflows with Claude! 🚀