temporal-mcp

⏰🧠 Temporal-MCP Server

Temporal MCP is an MCP server that bridges AI assistants (like Claude) and Temporal workflows. It turns complex backend orchestration into simple, chat-driven commands. Imagine triggering stateful processes without writing a line of glue code. Temporal-MCP makes that possible.

Why Temporal MCP

• Supercharged AI — AI assistants gain reliable, long-running workflow superpowers
• Conversational Orchestration — Trigger, monitor, and manage workflows through natural language
• Enterprise-Ready — Leverage Temporal's retries, timeouts, and persistence—exposed in plain text

✨ Key Features

• 🔍 Automatic Discovery — Explore available workflows and see rich metadata
• 🏃‍♂️ Seamless Execution — Kick off complex processes with a single chat message
• 📊 Real-time Monitoring — Follow progress, check status, and get live updates
• ⚡ Performance Optimization — Smart caching for instant answers
• 🧠 AI-Friendly Descriptions — Purpose fields written for both humans and machines

🏁 Getting Started

Prerequisites

• Go 1.21+ — For building and running the MCP server
• Temporal Server — Running locally or remotely (see Temporal docs)

Quick Install

1. Run your Temporal server and workers In this example, we'll use the Temporal Money Transfer Demo.

MCP Setup

Get Claude (or similar MCP-enabled AI assistant) talking to your workflows in 5 easy steps:

2. Build the server

git clone https://github.com/Mocksi/temporal-mcp.git
cd temporal-mcp
make build

2. Define your workflows in config.yml The sample configuration (config.sample.yml) is designed to work with the Temporal Money Transfer Demo:

workflows:
  AccountTransferWorkflow:
    purpose: "Transfers money between accounts with validation and notification. Handles the happy path scenario where everything works as expected."
    input:
      type: "TransferInput"
      fields:
        - from_account: "Source account ID"
        - to_account: "Destination account ID"
        - amount: "Amount to transfer"
    output:
      type: "TransferOutput"
      description: "Transfer confirmation with charge ID"
    taskQueue: "account-transfer-queue"

  AccountTransferWorkflowScenarios:
    purpose: "Extended account transfer workflow with various scenarios including human approval, recoverable failures, and advanced visibility features."
    input:
      type: "TransferInput"
      fields:
        - from_account: "Source account ID"
        - to_account: "Destination account ID"
        - amount: "Amount to transfer"
        - scenario_type: "Type of scenario to execute (human_approval, recoverable_failure, advanced_visibility)"
    output:
      type: "TransferOutput"
      description: "Transfer confirmation with charge ID"
    taskQueue: "account-transfer-queue"

3. Generate Claude's configuration

cd examples
./generate_claude_config.sh

4. Install the configuration

cp examples/claude_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

5. Start Claude with this configuration

Conversing with Your Workflows

Now for the magic part! Talk to your workflows through Claude using natural language:

💬 "Claude, can you transfer $100 from account ABC123 to account XYZ789?"

💬 "What transfer scenarios are available to test?"

💬 "Execute a transfer that requires human approval for $500 between accounts ABC123 and XYZ789"

💬 "Has the transfer workflow completed yet?"

💬 "Run a transfer scenario with recoverable failures to test error handling"

Behind the scenes, Temporal MCP translates these natural language requests into properly formatted workflow executions—no more complex API calls or parameter formatting!

Core Values

1. Clarity First — Use simple, direct language. Avoid jargon.
2. Benefit-Driven — Lead with "what's in it for me".
3. Concise Power — Less is more—keep sentences tight and memorable.
4. Personality & Voice — Bold statements, short lines, a dash of excitement.

Ready to Showcase

Lights, camera, action—capture your first AI-driven workflow in motion. Share that moment. Inspire others to see Temporal MCP in action.

Development

Project Structure

./
├── cmd/            # Entry points for executables
├── internal/       # Internal package code
│   ├── api/        # MCP API implementation
│   ├── cache/      # Caching layer
│   ├── config/     # Configuration management
│   └── temporal/   # Temporal client integration
├── examples/       # Example configurations and scripts
└── docs/           # Documentation

Common Commands

🔍 Troubleshooting

Common Issues

Connection Refused

• ✓ Check if Temporal server is running
• ✓ Verify hostPort is correct in config.yml

Workflow Not Found

• ✓ Ensure workflow is registered in Temporal
• ✓ Check namespace settings in config.yml

Claude Can't See Workflows

• ✓ Verify claude_config.json is in the correct location
• ✓ Restart Claude after configuration changes

⚙️ Configuration

The heart of Temporal MCP is its configuration file, which connects your AI assistants to your workflow engine:

Configuration Architecture

Your config.yml consists of three key sections:

1. 🔌 Temporal Connection — How to connect to your Temporal server
2. 💾 Cache Settings — Performance optimization for workflow results
3. 🔧 Workflow Definitions — The workflows your AI can discover and use

Example Configuration

The sample configuration is designed to work with the Temporal Money Transfer Demo:

# Temporal server connection details
temporal:
  hostPort: "localhost:7233"       # Your Temporal server address
  namespace: "default"             # Temporal namespace
  environment: "local"             # "local" or "remote"
  defaultTaskQueue: "account-transfer-queue"  # Default task queue for workflows

  # Fine-tune connection behavior
  timeout: "5s"                    # Connection timeout
  retryOptions:                     # Robust retry settings
    initialInterval: "100ms"       # Start with quick retries
    maximumInterval: "10s"         # Max wait between retries
    maximumAttempts: 5              # Don't try forever
    backoffCoefficient: 2.0         # Exponential backoff

# Define AI-discoverable workflows
workflows:
  AccountTransferWorkflow:
    purpose: "Transfers money between accounts with validation and notification. Handles the happy path scenario where everything works as expected."
    workflowIDRecipe: "transfer_{{.from_account}}_{{.to_account}}_{{.amount}}"
    input:
      type: "TransferInput"
      fields:
        - from_account: "Source account ID"
        - to_account: "Destination account ID"
        - amount: "Amount to transfer"
    output:
      type: "TransferOutput"
      description: "Transfer confirmation with charge ID"
    taskQueue: "account-transfer-queue"
    activities:
      - name: "validate"
        timeout: "5s"
      - name: "withdraw"
        timeout: "5s"
      - name: "deposit"
        timeout: "5s"
      - name: "sendNotification"
        timeout: "5s"
      - name: "undoWithdraw"
        timeout: "5s"

💡 Pro Tip: The sample configuration is pre-configured to work with the Temporal Money Transfer Demo. Use it as a starting point for your own workflows.

💎 Best Practices

Crafting Perfect Purpose Fields

The purpose field is your AI assistant's window into understanding what each workflow does. Make it count!

✅ Do This

• Write clear, detailed descriptions of functionality
• Mention key parameters and how they customize behavior
• Describe expected outputs and their formats
• Note any limitations or constraints

❌ Avoid This

• Vague descriptions ("Processes data")
• Technical jargon without explanation
• Missing important parameters
• Ignoring error cases or limitations

Before & After

Before: "Gets information about a file."

After: "Retrieves detailed metadata about a file or directory including size, creation time, last modified time, permissions, and type. Performs access validation to ensure the requested file is within allowed directories. Returns formatted JSON with all attributes or an appropriate error message."

Naming Conventions

Security Guidelines

⚠️ Important Security Notes:

• Keep credentials out of your configuration files
• Use environment variables for sensitive values
• Consider access controls for workflows with sensitive data
• Validate and sanitize all workflow inputs

💡 Tip: Create different configurations for development and production environments

Why Good Purpose Fields Matter

1. Enhanced AI Understanding - Claude and other AI tools can provide much more accurate and helpful responses when they fully understand the capabilities and limitations of each component
2. Fewer Errors - Detailed descriptions reduce the chances of AI systems using components incorrectly
3. Improved Debugging - Clear descriptions help identify issues when workflows don't behave as expected
4. Better Developer Experience - New team members can understand your system more quickly
5. Documentation As Code - Purpose fields serve as living documentation that stays in sync with the codebase

Contribute & Collaborate

We're building this together.

• Share your own workflow configs
• Improve descriptions
• Share your demos (video or GIF) in issues

Let's unleash the power of AI and Temporal together!

📜 License

This project is licensed under the MIT License - see the LICENSE file for details. Contributions welcome!