---
title: "MCP Time Server：把时区和时间换算交给标准工具"
wiki: mcp
category: "服务端开发"
slug: server-time
url: https://learnagent.wiki/mcp/cards/server-time
tags: ["MCP", "Time Server", "时区", "时间换算", "Reference Server"]
last_updated: 2026-04-11
reading_time: 10
---

> Time Server 是 MCP 官方 reference servers 里看起来最朴素，但实际上非常有用的一类。它解决的不是“问一句现在几点”，而是更通用的时间能力问题：

# MCP Time Server：把时区和时间换算交给标准工具

## 基础概念

Time Server 是 MCP 官方 reference servers 里看起来最朴素，但实际上非常有用的一类。它解决的不是“问一句现在几点”，而是更通用的时间能力问题：

- 获取某个时区当前时间
- 在不同时区之间做换算
- 基于 IANA timezone 名称进行标准化处理
- 自动检测本机系统时区，必要时允许覆盖

官方 README 的定位很清楚：**这是一个提供时间与时区转换能力的 MCP Server。**

这类能力为什么值得单独做成 Server？因为时间问题看着简单，实际上是最容易被“拍脑袋字符串处理”写坏的一类问题之一。只要你涉及：

- 跨国家团队
- 定时任务
- 远程会议
- 时区差和夏令时

把时间换算交给标准工具，通常比让模型自己口算更稳。

### 核心要素

| 要素 | 作用 |
|------|------|
| **当前时间查询** | `get_current_time` 用来查某个时区或本机时区当前时间 |
| **时区换算** | `convert_time` 用来在不同时区之间换算 HH:MM 形式时间 |
| **IANA 时区名** | 官方 README 明确要求使用如 `America/New_York`、`Europe/London` 这种标准时区名 |
| **系统时区检测** | 默认自动检测本机时区，必要时可通过参数或配置覆盖 |
| **结构化输出** | 返回的不只是文本，而是带 timezone、datetime、is_dst 等字段的结构化结果 |

### 它真正解决的问题

```mermaid
graph LR
    A["用户说：纽约下午 4 点"] --> B["Time Server 解析 source timezone"]
    B --> C["按目标 timezone 换算"]
    C --> D["返回结构化时间结果"]
```

### 为什么要强调 IANA 时区

```mermaid
graph TD
    A["'Tokyo time' / 'New York time' 这种自然语言"] --> B["容易含糊或依赖模型猜测"]
    C["Asia/Tokyo / America/New_York"] --> D["IANA 标准时区名"]
    D --> E["更适合程序处理和跨系统对齐"]
```

这就是官方 README 一开始就把 IANA timezone names 写进工具参数说明的原因。

## 基础用法

### 最小启动方式

官方推荐的最简单方式是：

```bash
uvx mcp-server-time
```

如果你习惯 `pip`，也可以：

```bash
pip install mcp-server-time
python -m mcp_server_time
```

### 在 Claude Desktop 中挂载

官方 README 的最小配置是：

```json
{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}
```

### 在 VS Code 中挂载

README 给出的 `.vscode/mcp.json` 形式是：

```json
{
  "mcp": {
    "servers": {
      "time": {
        "command": "uvx",
        "args": ["mcp-server-time"]
      }
    }
  }
}
```

### 查某个时区现在几点

官方 README 给出的典型调用参数是：

```json
{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Europe/Warsaw"
  }
}
```

返回结构里会包含：

- `timezone`
- `datetime`
- `is_dst`

这比只给一句“现在是下午几点”更适合程序和模型后续继续处理。

### 做时区换算

另一个常见调用是：

```json
{
  "name": "convert_time",
  "arguments": {
    "source_timezone": "America/New_York",
    "time": "16:30",
    "target_timezone": "Asia/Tokyo"
  }
}
```

这类结果除了源时区和目标时区的结构化时间，还会给你：

- `time_difference`

也就是时差本身。

### 自定义本地时区

官方 README 还说明了一个实用配置：如果默认系统时区检测不适合你的运行环境，可以显式传：

```json
{
  "command": "python",
  "args": [
    "-m",
    "mcp_server_time",
    "--local-timezone=America/New_York"
  ]
}
```

这对于容器、远程环境或者系统时区设置不干净的场景很有用。

## 同类工具对比

如果目标都是“让 AI 处理时间”，常见方式有三种：

| 维度 | Time Server | 模型直接口算 | 通用脚本 / Shell 时间命令 |
|------|-------------|--------------|---------------------------|
| 结构化程度 | **高** | 低 | 中 |
| 跨时区稳定性 | 高 | 一般，容易猜错 | 高，但要自己包成工具 |
| 对夏令时意识 | 更好 | 不稳定 | 取决于实现 |
| 跨客户端复用 | 能 | 不能 | 取决于你自己有没有封装 |
| 上手成本 | 低 | 最低 | 中 |

核心区别：

- **Time Server**：最适合标准化、可复用的时间能力。
- **模型直接口算**：适合很简单的问题，但不适合严肃时区换算。
- **通用脚本**：可行，但你得自己设计工具接口和跨客户端复用方式。

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为 Time Server 只是“查现在几点”的玩具 | 不对，它的重点是时区与换算标准化 |
| 以为随便写个 `New York` 就总能稳定工作 | 官方参数设计更强调 IANA 时区名，如 `America/New_York` |
| 以为模型自己算 13 小时时差就够了 | 遇到夏令时、边界时间和本地时区问题时，显式工具更稳 |
| 以为系统时区一定总能检测正确 | 不一定。官方 README 明确支持 `--local-timezone` 覆盖 |
| 以为它只适合 Claude Desktop | 不是。README 里同样有 VS Code、Zed、Zencoder 等配置方式 |
| 以为时间结果只会返回人类文本 | 不是。它返回带 `datetime` 和 `is_dst` 的结构化信息 |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **边界清楚**：就是做时间和时区，不会掺别的复杂语义 | **能力范围窄**：只解决时间问题，不是日历或调度系统 |
| **标准化强**：IANA 时区名 + 结构化结果很适合机器处理 | **输入要求稍严**：得尽量使用正确的时区标识 |
| **对跨时区协作很实用**：远程团队、国际会议都常用 | **场景简单时会显得“有点重”**：问一句本地现在几点，不一定总要开工具 |
| **支持本地时区自动检测和显式覆盖**：部署弹性好 | **不是完整日程系统**：不会帮你解决会议安排、节假日、工作日逻辑 |
| **跨客户端复用好**：不是写死在某个聊天产品里的小功能 | **仍要依赖宿主正确配置**：尤其容器 / 远程环境时区要注意 |

## 思考题

<details>
<summary>初级：为什么“纽约下午 4 点在东京是几点”这种问题，也值得专门用工具而不是让模型直接回答？</summary>

**参考答案：**

因为这类问题表面上像小学算术，实际上经常会踩进时区和夏令时的坑。

模型直接回答时，可能只是在“记忆里大概知道时差是多少”，而不是基于当前标准时区规则做精确换算。Time Server 的价值，就是把这种本来容易凭感觉乱算的问题，交给结构化工具。

</details>

<details>
<summary>中级：什么时候你应该显式传 `--local-timezone`，而不是依赖系统自动检测？</summary>

**参考答案：**

当你运行环境的“系统时区”不可信时，就应该显式传。

典型场景包括：

- Docker 容器里时区没配好
- 远程开发机的系统设置不是你真实所在时区
- CI / 云主机统一跑 UTC，但你希望工具按某个业务时区工作

这时手动指定会比“希望系统猜对”稳得多。

</details>

<details>
<summary>进阶：为什么 Time Server 的价值在团队协作里，往往比在个人使用里更明显？</summary>

**参考答案：**

因为个人场景里，你很多时候只关心自己本地时间，模型口头回答出错的代价也没那么高。

但在团队协作里，一旦跨时区：

- 开会时间
- 值班交接
- 发布窗口
- 截止时间

这些都需要对齐。Time Server 的价值就在于，它把这些时间转换交给统一工具来做，减少“大家脑补一个时差”的风险。

</details>

## 参考资料

1. 官方 Time reference server README：<https://github.com/modelcontextprotocol/servers/tree/main/src/time>（查询日期 2026-04-11）
2. 官方 Reference Servers 仓库：<https://github.com/modelcontextprotocol/servers>（查询日期 2026-04-11）

---
*Source: https://learnagent.wiki/mcp/cards/server-time*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*