Temporal MCP Server Cursor IDE Setup 2026

How do you set up a Temporal MCP server in Cursor? Install one of the community Temporal MCP implementations, point it at your running Temporal server with TEMPORAL_ADDRESS and TEMPORAL_NAMESPACE environment variables, add it to Cursor's mcp.json, and restart. There is no Temporal-maintained, official MCP server as of this writing — every implementation in circulation is a community project, built in Go, Node.js, or Python, against Temporal's public SDKs.

That matters more here than it does for most integrations on this site. When a vendor ships its own MCP server — Stripe, Square, GitHub — there's one canonical tool list and one place to check for changes. With Temporal, "the Temporal MCP server" actually means several independently maintained projects with overlapping but not identical tool names, different language runtimes, and different levels of activity. This guide covers the pattern shared by the Go SDK-based implementation, since it's straightforward to install and has a small, well-documented tool surface, and flags where other implementations diverge.

Why Use Temporal MCP in Cursor

Temporal orchestrates long-running, durable workflows — the kind of process that might span minutes, days, or months, survive process restarts, and need to coordinate retries, timeouts, and signals across services. Normally, checking on a workflow's state means the Temporal CLI (temporal workflow describe) or the Temporal Web UI. With an MCP connection, Cursor can:

This is most useful mid-debugging session: you're reading the code for a workflow, and instead of switching to a terminal to run temporal workflow describe, you ask Cursor directly and get the answer inline with the code you're already looking at.

Prerequisites

Step 1: Install a Temporal MCP Implementation

For the Go SDK-based server:

go install github.com/wricardo/temporal-mcp@latest

This builds a temporal-mcp binary and places it on your $GOPATH/bin (make sure that's on your PATH). Verify with:

temporal-mcp --help

Before you install anything named "temporal-mcp," check the specific repo. Because multiple community projects use similar names, confirm you're looking at the maintainer, last-commit date, and open-issue count of the one you're about to run — a workflow-orchestration MCP server sits closer to production infrastructure than a documentation-lookup server, and an abandoned or unmaintained package is a worse bet here than it would be for something lower-stakes.

Step 2: Add to Cursor's mcp.json

{
  "mcpServers": {
    "temporal-mcp": {
      "command": "temporal-mcp",
      "env": {
        "TEMPORAL_ADDRESS": "localhost:7233",
        "TEMPORAL_NAMESPACE": "default"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Restart Cursor after saving.

Step 3: Verify the Connection

In Cursor chat:

List my running Temporal workflows

The list_workflows tool requires a status parameter (running, completed, or failed) — if Cursor doesn't pass one automatically, tell it explicitly which status you want. A response with real workflow IDs from your Temporal server confirms the connection.

Tools This Implementation Exposes

Per the project's own documentation, the Go SDK-based server ships two primary tools:

list_workflows
Required parameter: status (one of running, completed, failed). Returns the filtered workflow list from your configured namespace.

describe_workflow
Required parameter: workflow_id. Optional parameter: run_id — if omitted, the tool describes the latest run for that workflow ID. Returns execution details: workflow ID, run ID, workflow type, status, and start/close timestamps.

That's a deliberately small surface — read-only workflow inspection, not workflow control. If you need to start workflows, send signals, or run batch operations from chat, check a different implementation's tool list before assuming this one supports it; some of the other community Temporal MCP projects expose a broader set (up to roughly 19 tools spanning lifecycle management, signaling, and cron-based schedule management on at least one implementation), but tool names and exact behavior are not standardized across projects the way they would be for an official, single-vendor server.

Practical Workflows

Debugging a stuck workflow

Describe workflow order-fulfillment-8821 in Temporal and tell me its current status and when it last made progress

Auditing failures after a deploy

List all failed Temporal workflows and summarize what they have in common

Cross-referencing code with running state

I'm reading the OrderFulfillmentWorkflow code — describe a currently running instance of it so I can see what state it's actually in

Local Dev Server vs. Temporal Cloud

For local development, temporal server start-dev (from the Temporal CLI) spins up a full Temporal server plus Web UI on your machine, and localhost:7233 with namespace default connects to it with zero extra config. For Temporal Cloud, TEMPORAL_ADDRESS becomes your namespace's specific gRPC endpoint, and depending on the implementation, you may need to supply mTLS client certificates as additional environment variables — this guide's minimal two-variable config is the local-dev case. Check the specific implementation's README for its Cloud/mTLS variable names before assuming they match another project's.

Troubleshooting

Server never appears in Cursor. Confirm temporal-mcp is actually on your PATH — run which temporal-mcp in a terminal outside Cursor first. A go install that succeeded but didn't add $GOPATH/bin to your shell's PATH is the most common cause of "the binary exists but Cursor can't find it."

Connection refused, or empty workflow lists. Confirm your local Temporal server is actually running (temporal server start-dev in a separate terminal, or check Temporal Cloud's status) and that TEMPORAL_ADDRESS matches the port it's actually listening on. localhost:7233 is the default, but a custom temporal server start-dev --port changes it.

Wrong namespace, or workflows you expect aren't showing up. TEMPORAL_NAMESPACE in the config has to match exactly. A workflow started against a namespace other than default (common once a team moves past local dev toward a shared or Cloud namespace) won't appear if the MCP config still says default.

No authentication configured, and that's making you nervous. You're right to be — the Go SDK-based implementation documented here has no built-in auth mechanism beyond network reachability to the Temporal server. For a local dev server this is normal (it's not exposed beyond your machine). For anything pointed at a shared or production Temporal Cloud namespace, the access boundary is entirely network-level (VPN, firewall rules, mTLS certs) rather than anything this MCP server enforces on its own — don't treat "the MCP server has no login prompt" as "this is safe to point at production with no other controls."

Tool call works but the result looks stale. Like most MCP servers, this is pull-based — it queries Temporal at the moment you ask, not on a live feed. A workflow that progressed between your last query and now needs a fresh describe_workflow call, not a re-read of the earlier chat response.

A different Temporal MCP project's README doesn't match this guide. That's expected, not a sign either project is wrong. Because there's no official Temporal-maintained server, tool names, required environment variables, and even the config key structure vary between the Go, Node.js, and Python community implementations. Treat each project's own README as the source of truth for that specific package rather than assuming this guide's list_workflows/describe_workflow pair is universal.

When Not to Use This

Temporal often orchestrates workflows with real side effects — payments, order fulfillment, provisioning infrastructure. A read-only inspection tool (list and describe) is low-risk. If you're evaluating one of the community implementations that exposes signal-sending or workflow-start tools, treat those the way you'd treat any write-capable MCP tool touching production infrastructure: require explicit confirmation on every call, and don't let an AI agent decide on its own that a stuck workflow should be signaled or terminated without a human checking which workflow ID it's actually targeting first.

Frequently Asked Questions

Q: Is there an official, Temporal-maintained MCP server?
A: Not as of this writing. Every Temporal MCP server in circulation — Go, Node.js, Python-based — is a community project built against Temporal's public SDKs, not something published under Temporal's own GitHub organization or documented on temporal.io's core docs.

Q: Which implementation should I use?
A: Depends on your stack and what you need. The Go SDK-based one covered in this guide has a small, well-documented read-only tool set (list and describe workflows) and is quick to install if you already have Go. Node.js and Python-based alternatives exist with different tool surfaces — check each project's own README, recent commit activity, and open issues before picking one, since none of them are the "official" choice by default.

Q: Can I start workflows or send signals through Temporal MCP, or only read state?
A: Depends on the implementation. The Go SDK-based server this guide focuses on exposes only list_workflows and describe_workflow — read-only. Other community implementations expose a broader tool set including signaling and schedule management. Check the specific project before assuming write capability either way.

Q: Does this require any authentication?
A: The Go SDK-based implementation has no documented authentication mechanism of its own — access control is whatever network boundary sits in front of your Temporal server (local-only, VPN, or mTLS certs for Temporal Cloud). Don't assume "no login prompt" means "safe to expose broadly."

Q: Does this work with Temporal Cloud, or only self-hosted/local Temporal?
A: Both, in principle — TEMPORAL_ADDRESS just needs to point at the right gRPC endpoint. Temporal Cloud typically requires additional mTLS certificate configuration beyond the two environment variables shown here for local dev; check your specific implementation's README for its Cloud-specific variable names.

Q: My workflow list is empty even though I know workflows are running.
A: Check TEMPORAL_NAMESPACE first — it has to match exactly, and workflows in a namespace other than the one configured simply won't appear, not error out. Confirm TEMPORAL_ADDRESS also points at the correct server before assuming something else is broken.

Related Guides

Official docs cited