# Temporal MCP Server

> Temporal MCP Server is an open-source MCP server for developer tools. Timezone conversion and DST-correct date arithmetic tools for AI assistants. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, API
- **Repository:** https://github.com/jordanburke/temporal-mcp-server
- **MCP Registry name:** io.github.jordanburke/temporal-mcp-server
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-15

## About

Language models are poor at clock arithmetic, and this server hands it to code. Four tools return the current time in any IANA timezone, convert a timestamp to another zone, add or subtract an ISO-8601 duration, and measure the elapsed time between two timestamps. The README leans on the difference between calendar and exact units: across the US fall-back change, adding P1D to midnight on 1 November gives midnight on 2 November (25 real hours), while PT24H gives 23:00 the same day.

Several behaviours are spelled out. Month arithmetic clamps instead of overflowing, so P1M on 31 January gives 28 February. Offsets come from the runtime's tz database per instant, so there is no table to go stale. A timestamp with no offset is read in the timezone you supply, never the host's. Parsing is strict ISO-8601, and errors name the bad value with the expected format so an agent can retry. time_between returns elapsed components with one shared sign and a past, future or same direction.

It runs locally over stdio, locally over HTTP on port 3333, or from a public Cloudflare Workers instance at time.somamcp.com. An optional MCP_AUTH_TOKEN secret protects your own deployment. It is built on somamcp and the functype library.

## Features

- **Current time anywhere:** Returns epoch, UTC ISO-8601 and wall-clock time in any IANA timezone.
- **Timezone conversion:** Renders an ISO-8601 timestamp in a target zone with the offset valid at that instant.
- **Calendar-aware durations:** Adds or subtracts ISO-8601 durations with DST and month-end handling.
- **Elapsed time:** Reports whole units and a readable summary between two timestamps.
- **Self-correcting errors:** Unknown timezones return the bad value and the expected format.
- **Three ways to run:** Use stdio, local HTTP or a hosted Cloudflare Workers instance.

## Good for

- Schedule a meeting across timezones without off-by-one-hour errors
- Compute a deadline that is one calendar day versus 24 hours away
- Work out how long until or since an event
- Find the right UTC offset for a city on a given date

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http temporal-mcp-server https://time.somamcp.com/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://time.somamcp.com/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "temporal-mcp-server": {
      "url": "https://time.somamcp.com/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "temporal-mcp-server": {
      "type": "http",
      "url": "https://time.somamcp.com/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "temporal-mcp-server": {
      "serverUrl": "https://time.somamcp.com/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "temporal-mcp-server": {
      "type": "http",
      "url": "https://time.somamcp.com/mcp"
    }
  }
}
```

## Tools

- `get_current_time`: Returns the current time as epoch, UTC ISO-8601 and wall-clock in any IANA timezone.
- `convert_timezone`: Renders an ISO-8601 timestamp in a target timezone.
- `add_duration`: Adds or subtracts an ISO-8601 duration with calendar-aware month arithmetic.
- `time_between`: Returns elapsed time between two timestamps in whole units plus a summary.
- `info`: Reports build and runtime information, registered by somamcp.

## FAQ

### Is there a hosted version?

Yes, https://time.somamcp.com/mcp runs on Cloudflare Workers; the same tools also run locally.

### What happens when adding one month to 31 January?

It clamps to the last valid day, giving 28 February in 2026.

### Does it use my computer's timezone for naive timestamps?

No. Timestamps without an offset are read in the timezone you supply.

### Which date formats are accepted?

Only ISO-8601; other forms such as 17 Aug 2026 are rejected with a hint.

### Can I require authentication on my own deployment?

Yes. Set the MCP_AUTH_TOKEN secret and unauthenticated calls to /mcp get a 401.

### Is Temporal MCP Server free?

Yes. Temporal MCP Server is open source, so you can use and self-host it for free.

### How do I add Temporal MCP Server to Claude Code?

Run this command in your terminal: claude mcp add --transport http temporal-mcp-server https://time.somamcp.com/mcp

### What are the best alternatives to Temporal MCP Server?

The closest alternatives to Temporal MCP Server are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/temporal-mcp-server
