npm package: @guanxiong/mcp-server-time
Description: A simple Model Context Protocol (MCP) server for getting current time with timezone support
Author: guanxiong.shen
Latest version: 1.0.0

# MCP Server Time

[![npm version](https://img.shields.io/npm/v/@guanxiong/mcp-server-time)](https://www.npmjs.com/package/@guanxiong/mcp-server-time)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@guanxiong/mcp-server-time)](https://nodejs.org/)

一个简单易用的 Model Context Protocol (MCP) 时间服务器，用于在 Cursor、Claude Desktop 等支持 MCP 的应用中方便地获取当前时间信息。

## ✨ 功能特性

- ✅ **获取当前时间** - 支持多种格式（ISO、本地格式、时间戳）
- ✅ **时区支持** - 支持所有 IANA 时区标识符
- ✅ **详细信息** - 获取年、月、日、时、分、秒、星期等详细信息
- ✅ **轻量级** - 零配置，开箱即用
- ✅ **跨平台** - 支持 Windows、macOS、Linux

## 📦 安装

### 方式一：使用 npx（推荐）

无需安装，直接使用：

```bash
# 在 MCP 配置中使用
npx -y @guanxiong/mcp-server-time
```

### 方式二：全局安装

```bash
npm install -g @guanxiong/mcp-server-time
```

### 方式三：本地安装

```bash
npm install @guanxiong/mcp-server-time
```

## 🚀 快速开始

### 配置 Cursor

编辑 `~/.cursor/mcp.json`（Windows: `C:\Users\<用户名>\.cursor\mcp.json`），添加以下配置：

```json
{
  "mcpServers": {
    "time-server": {
      "command": "npx",
      "args": [
        "-y",
        "@guanxiong/mcp-server-time"
      ]
    }
  }
}
```

### 配置 Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows），添加：

```json
{
  "mcpServers": {
    "time-server": {
      "command": "npx",
      "args": [
        "-y",
        "@guanxiong/mcp-server-time"
      ]
    }
  }
}
```

### 重启应用

配置完成后，重启 Cursor 或 Claude Desktop 使配置生效。

## 🛠️ 可用工具

### 1. get_current_time

获取当前日期和时间。

**参数**：
- `timezone` (可选): 时区标识符，例如 `Asia/Shanghai`、`UTC`、`America/New_York`
- `format` (可选): 时间格式
  - `iso`: ISO 8601 格式（默认）
  - `locale`: 本地化格式
  - `timestamp`: Unix 时间戳（毫秒）

**示例**：
```
用户：现在几点了？
AI：调用 get_current_time → 返回当前时间

用户：北京时间现在几点？
AI：调用 get_current_time，参数 timezone: "Asia/Shanghai"

用户：获取 UTC 时间戳
AI：调用 get_current_time，参数 format: "timestamp"
```

### 2. get_time_info

获取详细的时间信息，包括年、月、日、时、分、秒、星期等。

**参数**：
- `timezone` (可选): 时区标识符

**返回信息**：
- `year`: 年份
- `month`: 月份（1-12）
- `day`: 日期（1-31）
- `hour`: 小时（0-23）
- `minute`: 分钟（0-59）
- `second`: 秒（0-59）
- `weekday`: 星期几
- `timezone`: 时区

**示例**：
```
用户：今天是几号？星期几？
AI：调用 get_time_info → 返回详细信息
```

## 🌍 支持的时区

可以使用任何有效的 [IANA 时区标识符](https://www.iana.org/time-zones)，例如：

| 时区 | 标识符 | UTC 偏移 |
|------|--------|----------|
| 中国标准时间 | `Asia/Shanghai` | UTC+8 |
| 协调世界时 | `UTC` | UTC+0 |
| 美国东部时间 | `America/New_York` | UTC-5/-4 |
| 美国西部时间 | `America/Los_Angeles` | UTC-8/-7 |
| 英国时间 | `Europe/London` | UTC+0/+1 |
| 日本时间 | `Asia/Tokyo` | UTC+9 |
| 法国时间 | `Europe/Paris` | UTC+1/+2 |

## 📋 使用示例

### 示例 1：获取当前时间

```
用户：现在几点了？
```

**返回**：
```json
{
  "time": "2025-12-27T09:38:01.938Z",
  "timezone": "Asia/Shanghai",
  "format": "iso"
}
```

### 示例 2：获取指定时区时间

```
用户：纽约现在几点？
```

**返回**：
```json
{
  "time": "2025-12-27T04:38:01.938Z",
  "timezone": "America/New_York",
  "format": "iso"
}
```

### 示例 3：获取时间戳

```
用户：当前时间戳是多少？
```

**返回**：
```json
{
  "time": "1735292625123",
  "timezone": "Asia/Shanghai",
  "format": "timestamp"
}
```

### 示例 4：获取详细时间信息

```
用户：今天是几号？星期几？
```

**返回**：
```json
{
  "year": 2025,
  "month": 12,
  "day": 27,
  "hour": 17,
  "minute": 38,
  "second": 1,
  "weekday": "星期五",
  "timezone": "Asia/Shanghai"
}
```

## 🔧 故障排除

### 工具不可用

1. **确认已重启应用** - 配置更改后必须重启 Cursor/Claude Desktop
2. **检查配置文件路径** - 确保配置文件路径正确
3. **检查 JSON 格式** - 确保 JSON 格式正确，无语法错误
4. **检查 Node.js 版本** - 需要 Node.js >= 18.0.0

### 服务器无法启动

1. **检查 Node.js 版本**：
   ```bash
   node -v  # 需要 >= 18.0.0
   ```

2. **手动测试服务器**：
   ```bash
   npx -y @guanxiong/mcp-server-time
   ```
   应该无输出（使用 stdio 通信）

3. **检查网络连接** - 使用 npx 需要网络连接下载包

### 时区错误

1. **确认时区标识符正确** - 使用标准 IANA 时区标识符
2. **检查时区名称大小写** - 时区名称区分大小写
3. **不指定时区** - 如果不指定，将使用系统默认时区

## 📚 相关资源

- [Model Context Protocol 文档](https://modelcontextprotocol.io/)
- [IANA 时区数据库](https://www.iana.org/time-zones)
- [Node.js Date 对象文档](https://nodejs.org/api/date.html)
- [Cursor IDE](https://cursor.sh/)
- [Claude Desktop](https://claude.ai/desktop)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 更新日志

### 1.0.0 (2025-12-27)

- ✨ 初始版本发布
- ✅ 支持获取当前时间（多种格式）
- ✅ 支持时区设置
- ✅ 支持获取详细时间信息

## 📄 许可证

本项目采用 [MIT](LICENSE) 许可证。

## 🙏 致谢

- [Model Context Protocol](https://modelcontextprotocol.io/) - 提供 MCP 协议和 SDK
- 所有贡献者和用户

---

**Made with ❤️ for the MCP community**