Time MCP
一个时间处理的 MCP (Model Context Protocol) 工具,基于 Python + FastMCP 构建。
功能特性
| 工具 | 说明 |
|---|---|
get_current_time | 获取当前时间 |
time_calculate | 时间计算(加减年/月/日/时/分/秒) |
timezone_convert | 时区转换 |
list_timezones | 列出可用时区 |
核心特性
- 🕐 默认使用北京时间(Asia/Shanghai)
- 🔢 时间戳自动识别(10 位秒级 / 13 位毫秒级)
- 📅 支持多种时间输入格式
- 🌍 支持全球时区转换
安装
使用 uv(推荐)
git clone https://github.com/xbsheng/time-mcp.git
cd time-mcp
uv sync
使用 pip
pip install fastmcp python-dateutil pytz
使用方法
启动 MCP 服务
服务默认使用 HTTP 方式运行在 8000 端口:
uv run python src/server.py
启动后,MCP 服务将在 http://localhost:8000 上监听。
在 Cursor 中配置
在 ~/.cursor/mcp.json 中添加:
{
"mcpServers": {
"time-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}
或者使用命令行方式(无需单独启动服务):
{
"mcpServers": {
"time-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/time-mcp", "run", "python", "src/server.py"]
}
}
}
在 Claude Desktop 中配置
在 Claude Desktop 配置文件中添加:
{
"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 | - | 自定义输出格式 |
返回示例:
{
"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 >= 2.0.0 - MCP 服务框架
- python-dateutil - 时间解析
- pytz - 时区支持
开源协议
本项目采用 MIT License 开源协议。
