Temporal MCP server
Commit Nov 13, 2026Allows AI agents to investigate Temporal workflows, check task queue status, and manage workflow runs via namespaces.
Also known as temporalio/temporal-mcp
- Stars
- 9
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is Temporal MCP?
Temporal allows AI agents to investigate Temporal workflows, check task queue status, and manage workflow runs via namespaces.
Summary generated from the project's README
About Temporal MCP server
Investigating Temporal workflows and managing task queues from within an AI agent is what temporal-mcp enables. Developers can use this server to inspect workflow states, examine event histories, and monitor task queue backlogs or pollers. It provides tools to list namespaces, search for specific workflow runs using visibility queries, and even start new workflow runs.
Individual developers can run the server locally via stdio by connecting it to an agent like Claude Code or Codex using a YAML configuration file. For organizational use, the server can be deployed as a centrally hosted HTTPS service where users authenticate through an OpenID Connect identity provider. While most tools are read-only for safety, the start_workflow tool allows for active management. The server supports connecting to local development servers, self-hosted instances, or Temporal Cloud namespaces using API keys or mTLS.
What you can do with it
- 1Debug stuck workflowsAsk an AI agent to determine why a specific workflow execution is not progressing.
- 2Monitor task queue healthHave an agent check if any workers are currently active on a specific task queue.
- 3Analyze workflow failuresRequest a summary of all workflow runs that encountered errors within a specific timeframe.
- 4Verify server connectivityUse the agent to confirm that the MCP server can successfully reach a configured Temporal namespace.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletemporalio/temporal-mcp is public and reachablegithub.com/temporalio/temporal-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/temporalio/temporal-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtemporal-mcp (Pre-release)
temporal-mcp is an MCP server that gives AI agents access to the Temporal namespaces listed in its config, over streamable HTTP or, for one developer, over stdio. Its tools let an agent list the namespaces it can use and check that the server can reach each one, read a workflow run's state and event history or a summary of that history, see a task queue's pollers and backlog, list a namespace's search attributes, search and count workflow runs with Visibility queries, and start workflow runs. Every tool but start_workflow only reads.
[!NOTE]
Pre-release: This project is under active development and evolving quickly. It is not ready for production use. Open a GitHub issue if you have questions or want to follow along. If you're evaluating this project for your organization, read the request for comment and reach out to your Temporal representative for guidance and to share feedback.
Get started
These steps set up temporal-mcp for one developer, whose agent launches it and talks to it over stdio. You try it on a local Temporal dev server first, then add your own namespaces. When you're ready, go to Run a centrally hosted server to set up this MCP server for a broader audience.
Install
curl -sSfL https://temporal.download/mcp.sh | sh
temporal-mcp --version # checks the install
Each release is also published as the container image temporalio/temporal-mcp:<version> on Docker Hub.
Start a dev server
Install the Temporal CLI and start a dev server, which serves a default namespace at localhost:7233:
temporal server start-dev
Configure
temporal-mcp reads one YAML config, passed with --config. Copy examples/stdio-local-config.yaml, whose local target is the dev server.
Connect
Add temporal-mcp to your agent with --stdio and the absolute path of your config, since the agent starts the server from its own working directory. For Claude Code, with --scope user so the server is available to you in every project, instead of only in the current directory:
claude mcp add --scope user temporal -- temporal-mcp --stdio --config /absolute/path/to/config.yaml
For Codex:
codex mcp add temporal -- temporal-mcp --stdio --config /absolute/path/to/config.yaml
Other agents take the same command, arguments and environment variables in their own config format.
Check
Ask the agent to check its connection to the local target. It calls check_connection, which reports whether the server can reach the dev server and its default namespace.
Once your app runs workflows on the dev server, or once you add your own namespaces, ask the agent about them, for example:
- Why is workflow
order-123stuck? - Which workflow runs failed in the last hour?
- Is any worker polling the
orderstask queue?
Add your own namespaces
To use your Temporal Cloud or self-hosted namespaces, add a target for each one to your config. The payments-staging target in examples/stdio-config.yaml shows a Temporal Cloud namespace with an API key, and docs/config.md documents every field.
For each environment variable your config reads with env:, add -e KEY=value (Claude Code) or --env KEY=value (Codex) just before the --. To change the command, run it again: codex mcp add replaces the server of the same name, but for Claude Code, run claude mcp remove temporal first.
The server reads its config only when it starts, so restart your agent after you change the config, then ask it to check its connection to each new target.
Run a centrally hosted server
For a team or an entire organization, run temporal-mcp as one HTTPS server whose users sign in with an OpenID Connect (OIDC) identity provider. Start with the deployment guide. The identity and access guide explains the identity provider and authorization setup, the API-key example and mTLS example show complete configs, and the config reference documents every field.
Without --stdio, temporal-mcp serves MCP at /mcp on the config's listen address:
./temporal-mcp --config config.yaml
Audit records and logs
temporal-mcp writes an audit record of each tool call that passes the token check to stdout, as one line of JSON, and its logs to stderr. With --stdio, both go to stderr, and each record's issuer and subject are null because there is no token. audit_log_file and error_log_file send the audit records and the logs to files instead.
Build from source
With Go 1.27.2 or later:
go build -o bin/ .
This writes bin/temporal-mcp. To build a container image instead, whose entrypoint is temporal-mcp, and run it with your config:
docker build -t temporal-mcp .
docker run -v /path/to/config.yaml:/config.yaml:ro temporal-mcp --config /config.yaml
Shutdown
On SIGINT or SIGTERM, temporal-mcp stops accepting new requests and waits up to shutdown_timeout for the tool calls in progress to finish. With --stdio, closing stdin also starts this shutdown, and stdout stays open for the calls' responses:
shutdown_timeout: 25s # 8s if unset
It then cancels the calls still running, which get audit records with outcome cancelled, and exits within another second. Set shutdown_timeout at least a second shorter than the time your platform allows between SIGTERM and SIGKILL.
Calls interrupted by shutdown return a tool error with code server_shutting_down, message the server is shutting down, and retryable: true.
A second signal stops temporal-mcp at once. A call cut off that way, or by SIGKILL, gets no audit record.
Temporal MCP questions
Is this server ready for production use?
No, this is a pre-release project under active development and is not yet ready for production.
What can an AI agent do with this server?
An agent can list namespaces, check connectivity, read workflow state and event history, monitor task queues, search workflow runs, and start new workflow runs.
How can I run this for a team or organization?
You can run it as a centrally hosted HTTPS server where users sign in using an OpenID Connect (OIDC) identity provider.