# Time MCP
一个时间处理的 MCP (Model Context Protocol) 工具，基于 Python + FastMCP 构建。
## 功能特性
| 工具 | 说明 |
| ------------------ | --------------------------------- |
| `get_current_time` | 获取当前时间 |
| `time_calculate` | 时间计算（加减年/月/日/时/分/秒） |
| `timezone_convert` | 时区转换 |
| `list_timezones` | 列出可用时区 |
### 核心特性
- 🕐 默认使用北京时间（Asia/Shanghai）
- 🔢 时间戳自动识别（10 位秒级 / 13 位毫秒级）
- 📅 支持多种时间输入格式
- 🌍 支持全球时区转换
## 安装
### 使用 uv（推荐）
```bash
git clone https://github.com/xbsheng/time-mcp.git
cd time-mcp
uv sync
```
### 使用 pip
```bash
pip install fastmcp python-dateutil pytz
```
## 使用方法
### 启动 MCP 服务
服务默认使用 HTTP 方式运行在 8000 端口：
```bash
uv run python src/server.py
```
启动后，MCP 服务将在 `http://localhost:8000` 上监听。
### 在 Cursor 中配置
在 `~/.cursor/mcp.json` 中添加：
```json
{
"mcpServers": {
"time-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}
```
或者使用命令行方式（无需单独启动服务）：
```json
{
"mcpServers": {
"time-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/time-mcp", "run", "python", "src/server.py"]
}
}
}
```
### 在 Claude Desktop 中配置
在 Claude Desktop 配置文件中添加：
```json
{
"mcpServers": {
"time-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/time-mcp", "run", "python", "src/server.py"]
}
}
}
```
## 工具详细说明
### get_current_time
获取当前时间，返回多种格式。
**参数：**
| 参数 | 类型 | 默认值 | 说明 |
| ---------- | ------ | ------------- | -------------- |
| `timezone` | string | Asia/Shanghai | 时区 |
| `format` | string | - | 自定义输出格式 |
**返回示例：**
```json
{
"datetime": "2026-01-12 22:00:00",
"date": "2026-01-12",
"time": "22:00:00",
"timestamp": 1768226400,
"timestamp_ms": 1768226400000,
"timezone": "Asia/Shanghai",
"iso": "2026-01-12T22:00:00+08:00",
"weekday": "Monday",
"weekday_cn": "周一"
}
```
### time_calculate
时间计算，对指定时间进行加减运算。
**参数：**
| 参数 | 类型 | 默认值 | 说明 |
| ----------- | ---------- | ------------- | ------------------------------ |
| `base_time` | string/int | 当前时间 | 基准时间（时间戳或日期字符串） |
| `years` | int | 0 | 加减年数 |
| `months` | int | 0 | 加减月数 |
| `days` | int | 0 | 加减天数 |
| `hours` | int | 0 | 加减小时数 |
| `minutes` | int | 0 | 加减分钟数 |
| `seconds` | int | 0 | 加减秒数 |
| `timezone` | string | Asia/Shanghai | 时区 |
**使用示例：**
```
# 当前时间加7天
time_calculate(days=7)
# 指定时间减1个月
time_calculate(base_time="2026-01-01", months=-1)
# 时间戳加8小时
time_calculate(base_time=1704067200, hours=8)
```
### timezone_convert
时区转换，将时间转换为指定时区。
**参数：**
| 参数 | 类型 | 默认值 | 说明 |
| --------- | ---------- | ------------- | -------- |
| `time` | string/int | - | 输入时间 |
| `from_tz` | string | Asia/Shanghai | 源时区 |
| `to_tz` | string | - | 目标时区 |
**使用示例：**
```
# 北京时间转纽约时间
timezone_convert(time="2026-01-12 12:00:00", to_tz="America/New_York")
```
### list_timezones
列出可用时区。
**参数：**
| 参数 | 类型 | 默认值 | 说明 |
| -------- | ------ | ------ | -------------------------------------- |
| `region` | string | - | 按区域筛选（如 Asia, America, Europe） |
## 项目结构
```
time-mcp/
├── src/
│ ├── __init__.py
│ └── server.py # MCP 服务主文件
├── pyproject.toml # 项目配置
├── uv.lock # 依赖锁定
├── LICENSE
└── README.md
```
## 技术栈
- Python 3.11+
- [FastMCP](https://github.com/jlowin/fastmcp) >= 2.0.0 - MCP 服务框架
- [python-dateutil](https://github.com/dateutil/dateutil) - 时间解析
- [pytz](https://pythonhosted.org/pytz/) - 时区支持
## 开源协议
本项目采用 [MIT License](LICENSE) 开源协议。
