temporal

Temporal MCP is a bridge between AI assistants and Temporal workflows. It exposes a conversational interface that lets you discover available workflows, kick off long-running Temporal executions, monitor progress, and receive live updates through natural language. You can describe transfers, approvals, or multi-step orchestrations in plain text and Temporal MCP translates those intents into Temporal workflow invocations, handling inputs, retries, timeouts, and task queues behind the scenes. The server also surfaces metadata about workflows to help AI assistants choose the right actions and parameters.

To get started, run the MCP server locally after building the binary. Once running, connect an AI assistant (for example Claude or another MCP-enabled agent) to the Temporal MCP endpoint. Use the provided sample workflows and the config.yml to ensure your workflows are discoverable. You can query available workflows, view their inputs and outputs, and then issue natural language commands like “start AccountTransferWorkflow to move 100 from ACCT-1 to ACCT-2” or “check status of the latest transfer.” The system will execute the corresponding Temporal workflow, report back results, and offer real-time progress updates.

Prerequisites:

• Go 1.21+ installed on your machine
• Temporal Server reachable (local or remote)
• Git installed

Installation steps:

1. Clone the repository

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

2. Build the MCP server binary

make build

(or build directly with Go if you prefer)

go build -o bin/temporal-mcp ./...

3. Ensure Temporal server is running and accessible

• If you’re following the sample, run the Temporal Money Transfer Demo or point to your Temporal deployment.

4. Prepare configuration

• Create or edit config.yml to define workflows, Temporal connection, and task queues as shown in the README sample.

5. Run the MCP server

./bin/temporal-mcp

6. Connect your MCP-enabled AI assistant (Claude or similar) to the MCP endpoint you started (e.g., http://localhost:PORT).

Tips and common issues:

• Make sure Temporal is accessible at the hostPort defined in your config.yml (e.g., localhost:7233).
• If Claude cannot see workflows, verify claude_config.json is in the correct location and that the workflows are registered in Temporal.
• When tweaking retries and timeouts, adjust the temporal section of config.yml carefully to avoid excessive backoff or short timeouts.
• Ensure the sample config’s taskQueue names (e.g., account-transfer-queue) exist in Temporal and match your workflow definitions.
• For development, use make fmt and go vet to keep code clean and consistent.