TimezoneToolkit MCP Server

<div align="center">
  <img src="logo.png" alt="TimezoneToolkit Logo" width="200"/>
  <h1>TimezoneToolkit MCP 服务器</h1>
  <p>一个高级 MCP (模型上下文协议) 服务器，提供全面的时间和时区工具，具有超越基本转换的增强功能。</p>
</div>

## 可用工具

| 工具 | 描述 |
| ---- | ----------- |
| convert_time | 将时间从一个时区转换为另一个时区 |
| get_current_time | 获取指定时区的当前时间 |
| calculate_sunrise_sunset | 计算特定位置和日期的日出、日落和暮光时间 |
| calculate_moon_phase | 计算特定日期的月相 |
| calculate_timezone_difference | 计算两个时区之间的时间差 |
| list_timezones | 列出可用的 IANA 时区，可以选择按区域过滤 |
| calculate_countdown | 计算到特定日期/事件的剩余时间 |
| calculate_business_days | 计算两个日期之间的工作日（不包括周末） |
| format_date | 以各种样式格式化日期 |

## 🌟 功能

### 🕒 基本时区转换
- 在任何 IANA 时区之间转换时间
- 获取任何时区的当前时间
- 以各种样式（短、中、长）格式化时间
- 计算小时/分钟的时间差
- 列出可用的 IANA 时区

### 🌅 日出/日落和天文计算
- 计算任何位置的日出和日落时间
- 包括暮光时间（民用、航海、天文）
- 计算任何位置/日期的日长
- 计算任何日期的月相

### 📅 日期和时间实用程序
- 以各种样式（短、中、长、ISO、相对）格式化日期
- 计算日期之间的工作日
- 创建到未来事件的倒计时计时器
- 支持多种语言环境和时区

## 💻 安装

### 前提条件

- Node.js 18.x 或更高版本 - TimezoneToolkit MCP 服务器需要 Node.js 18+ 才能正常运行。

### 设置

要使用 Node.js npx 运行 TimezoneToolkit MCP 服务器，请使用以下命令：

```bash
npx -y @cicatriz/timezone-toolkit@latest

客户端特定安装

Cursor

要将此服务器添加到 Cursor IDE：

1. 转到 Cursor 设置 > MCP
2. 单击 + 添加新的全局 MCP 服务器
3. 将以下配置添加到您的全局 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

有关更多详细信息，请参阅 Cursor 文档。

Windsurf

要使用 Cascade 设置 MCP，请导航到 Windsurf - 设置 > 高级设置或命令面板 > 打开 Windsurf 设置页面。

向下滚动到 Cascade 部分，并在 mcp_config.json 中直接添加 TimezoneToolkit MCP 服务器：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Cline

通过 Cline MCP 服务器设置，手动将以下 JSON 添加到您的 cline_mcp_settings.json：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Roo Code

通过单击 Roo Code 设置中的“编辑 MCP 设置”或使用 VS Code 命令面板中的“Roo Code: 打开 MCP 配置”命令来访问 MCP 设置：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Claude

将以下内容添加到您的 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

有关更多详细信息，请参阅 Claude Desktop 文档。

CLI

您也可以通过运行以下命令将其作为 CLI 运行：

npx -y @cicatriz/timezone-toolkit@latest

其他安装方法

从 npm 安装

# 从 npm 全局安装
npm install -g @cicatriz/timezone-toolkit

# 运行服务器
timezone-toolkit

手动安装

# 克隆存储库
git clone https://github.com/Cicatriiz/timezone-toolkit.git
cd timezone-toolkit

# 安装依赖项
npm install

# 构建项目
npm run build

# 运行服务器
node dist/index.js

💬 与 Claude Desktop 一起使用

安装后，您可以将 TimezoneToolkit 与 Claude Desktop 一起使用：

1. 打开 Claude Desktop
2. 开始新的对话
3. 单击锤子图标以查看可用工具
4. 选择任何 TimezoneToolkit 工具

🔗 API 访问

TimezoneToolkit 还提供了一个 RESTful API，用于在没有 Claude Desktop 的情况下访问其功能：

启动 API 服务器

# 使用 npm
npm install -g @cicatriz/timezone-toolkit
node server.js

API 服务器将在 http://localhost:3000 上可用

API 端点

• GET /api/tools - 列出所有可用工具
• POST /api/convert-time - 在时区之间转换时间
• POST /api/current-time - 获取时区的当前时间
• POST /api/sunrise-sunset - 计算日出/日落时间
• POST /api/moon-phase - 计算月相
• POST /api/timezone-difference - 计算时区差异
• POST /api/list-timezones - 列出可用的时区
• POST /api/countdown - 计算到日期的倒计时
• POST /api/business-days - 计算日期之间的工作日
• POST /api/format-date - 格式化日期

有关详细的 API 文档，请参阅 API README。

示例查询

• "东京现在几点？"
• "将纽约时间下午 3:00 转换为伦敦时间"
• "旧金山明天几点日出？"
• "巴黎今天几点日落？"
• "当前的月相是什么？"
• "纽约和东京之间的时差是多少？"
• "给我显示一个欧洲时区列表"
• "3 月 1 日到 4 月 15 日之间有多少个工作日？"
• "以法语区域设置格式化今天的日期"
• "到除夕还有多少时间？"

🔧 可用工具

1. convert_time

将时间从一个时区转换为另一个时区。

参数：

• time（可选）：要转换的时间（ISO 字符串或自然语言）。如果未提供，则默认为当前时间。
• fromTimezone：源 IANA 时区名称（例如，“America/New_York”）
• toTimezone：目标 IANA 时区名称（例如，“Europe/London”）
• format（可选）：输出格式（“short”、“medium”、“full”）。默认为“medium”

示例：

{
  "time": "2023-12-25T14:30:00",
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "format": "full"
}

响应：

{
  "originalTime": "2023-12-25T14:30:00.000-05:00",
  "convertedTime": "2023 年 12 月 26 日星期二凌晨 4:30:00 日本标准时间",
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "timeDifference": "+14 小时"
}

2. get_current_time

获取指定时区的当前时间。

参数：

• timezone：IANA 时区名称（例如，“Asia/Tokyo”）
• format（可选）：输出格式（“short”、“medium”、“full”）。默认为“medium”

示例：

{
  "timezone": "Europe/London",
  "format": "full"
}

响应：

{
  "currentTime": "2025 年 3 月 25 日星期一晚上 10:15:30 英国夏令时",
  "timezone": "Europe/London",
  "utcOffset": "+01:00"
}

3. calculate_sunrise_sunset

计算特定位置和日期的日出、日落和暮光时间。

参数：

• date（可选）：用于计算的日期（ISO 字符串或自然语言）。默认为当前日期。
• latitude：位置的纬度（-90 到 90）
• longitude：位置的经度（-180 到 180）
• timezone（可选）：IANA 时区名称（例如，“Europe/Paris”）。默认为 UTC。

示例：

{
  "date": "2023-06-21",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": "America/Los_Angeles"
}

响应：

{
  "date": "2023-06-21",
  "sunrise": "凌晨 05:48:11",
  "sunset": "晚上 08:35:13",
  "civilTwilight": {
    "dawn": "凌晨 05:17:22",
    "dusk": "晚上 09:06:02"
  },
  "nauticalTwilight": {
    "dawn": "凌晨 04:38:43",
    "dusk": "晚上 09:44:41"
  },
  "astronomicalTwilight": {
    "dawn": "凌晨 03:52:50",
    "dusk": "晚上 10:30:34"
  },
  "dayLength": "14 小时 47 分钟",
  "timezone": "America/Los_Angeles"
}

4. calculate_moon_phase

计算特定日期的月相。

参数：

• date（可选）：用于计算的日期（ISO 字符串或自然语言）。默认为当前日期。
• timezone（可选）：IANA 时区名称（例如，“Europe/Paris”）。默认为 UTC。

示例：

{
  "date": "2023-01-06",
  "timezone": "UTC"
}

响应：

{
  "date": "2023-01-06",
  "phase": 0.998,
  "phaseName": "满月",
  "illumination": 0.997,
  "timezone": "UTC"
}

5. calculate_timezone_difference

计算两个时区之间的时间差。

参数：

• fromTimezone：源 IANA 时区名称（例如，“America/New_York”）
• toTimezone：目标 IANA 时区名称（例如，“Europe/London”）

示例：

{
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo"
}

响应：

{
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "timeDifference": "+14 小时",
  "currentTimeFrom": "2025 年 3 月 25 日，下午 6:15",
  "currentTimeTo": "2025 年 3 月 26 日，上午 8:15",
  "hoursDifference": 14,
  "minutesDifference": 0,
  "totalMinutesDifference": 840,
  "direction": "ahead"
}

6. list_timezones

列出可用的 IANA 时区，可以选择按区域过滤。

参数：

• region（可选）：按区域过滤时区（例如，“America”、“Europe”、“Asia”）

示例：

{
  "region": "Europe"
}

响应：

{
  "timezones": [
    {
      "timezone": "Europe/Amsterdam",
      "currentTime": "2025 年 3 月 25 日，晚上 11:15",
      "offset": "+02:00"
    },
    {
      "timezone": "Europe/Berlin",
      "currentTime": "2025 年 3 月 25 日，晚上 11:15",
      "offset": "+02:00"
    },
    // 其他欧洲时区...
  ],
  "count": 7,
  "region": "Europe"
}

7. calculate_countdown

计算到特定日期/事件的剩余时间。

参数：

• targetDate：目标日期/时间（ISO 字符串或自然语言）
• timezone（可选）：IANA 时区名称（例如，“America/New_York”）。默认为系统时区。
• title（可选）：事件的标题或名称

示例：

{
  "targetDate": "2025-12-31T23:59:59",
  "timezone": "UTC",
  "title": "除夕"
}

响应：

{
  "title": "除夕",
  "targetDate": "2025-12-31T23:59:59.000Z",
  "formattedTargetDate": "2025 年 12 月 31 日星期三晚上 11:59:59 GMT",
  "currentDate": "2025-03-25T18:15:30.000Z",
  "timezone": "UTC",
  "isPast": false,
  "countdown": "9 个月，6 天，5 小时，44 分钟，29 秒",
  "remaining": {
    "years": 0,
    "months": 9,
    "days": 6,
    "hours": 5,
    "minutes": 44,
    "seconds": 29,
    "totalDays": 281,
    "totalHours": 6749,
    "totalMinutes": 404969,
    "totalSeconds": 24298169
  }
}

8. calculate_business_days

计算两个日期之间的工作日（不包括周末）。

参数：

• startDate：开始日期（ISO 字符串或自然语言）
• endDate：结束日期（ISO 字符串或自然语言）
• timezone（可选）：IANA 时区名称（例如，“America/New_York”）。默认为系统时区。
• excludeHolidays（可选）：是否排除常见节假日（仅限美国节假日）。默认为 false。

示例：

{
  "startDate": "2023-05-01",
  "endDate": "2023-05-31",
  "timezone": "UTC",
  "excludeHolidays": true
}

响应：

{
  "startDate": "2023-05-01",
  "endDate": "2023-05-31",
  "businessDays": 22,
  "calendarDays": 31,
  "weekendDays": 8,
  "holidaysExcluded": 1,
  "timezone": "UTC",
  "businessDatesIncluded": ["2023-05-01", "2023-05-02", "2023-05-03", "2023-05-04", "2023-05-05", "2023-05-08", "2023-05-09", "2023-05-10", "2023-05-11", "2023-05-12", "2023-05-15", "2023-05-16", "2023-05-17", "2023-05-18", "2023-05-19", "2023-05-22", "2023-05-23", "2023-05-24", "2023-05-25", "2023-05-26", "2023-05-30", "2023-05-31"]
}

9. format_date

以各种样式格式化日期。

参数：

• date：要格式化的日期（ISO 字符串或自然语言）。默认为当前日期。
• timezone（可选）：IANA 时区名称（例如，“America/New_York”）。默认为系统时区。
• format（可选）：输出格式（“short”、“medium”、“full”、“iso”、“relative”）。默认为“medium”。
• locale（可选）：用于格式化的区域设置（例如，“en-US”、“fr”、“de”）。默认为“en-US”。

示例：

{
  "date": "2023-12-25",
  "timezone": "Europe/Paris",
  "format": "full",
  "locale": "fr"
}

响应：

{
  "originalDate": "2023-12-25",
  "parsedDate": "2023-12-25T00:00:00.000+01:00",
  "formattedDate": "lundi 25 décembre 2023",
  "formattedTime": "00:00:00 heure normale d'Europe centrale",
  "formattedDateTime": "lundi 25 décembre 2023 à 00:00:00 heure normale d'Europe centrale",
  "dayOfWeek": "lundi",
  "dayOfMonth": 25,
  "month": "décembre",
  "year": 2023,
  "timezone": "Europe/Paris",
  "locale": "fr",
  "format": "full"
}

💬 Claude Desktop 中的示例查询

• "东京现在几点？"
• "将纽约时间下午 3:00 转换为伦敦时间"
• "旧金山明天几点日出？"
• "巴黎今天几点日落？"
• "当前的月相是什么？"
• "纽约和东京之间的时差是多少？"
• "给我显示一个欧洲时区列表"
• "3 月 1 日到 4 月 15 日之间有多少个工作日？"
• "以法语区域设置格式化今天的日期"
• "到除夕还有多少时间？"

💻 技术细节

架构

TimezoneToolkit 使用模型上下文协议 (MCP) 规范构建，这使其可以与 Claude Desktop 无缝集成。 该服务器用 TypeScript 实现，并使用以下架构：

• 核心服务：实现时区转换、天文计算和日期格式化
• MCP 服务器：处理来自 Claude Desktop 的 JSON-RPC 请求
• 实用程序函数：为日期/时间操作提供辅助函数
• 测试框架：包括用于验证功能的综合测试脚本

依赖项

• Luxon - 用于所有日期/时间处理和时区操作
• SunCalc - 用于日出/日落和天文计算
• @modelcontextprotocol/sdk - 用于 MCP 服务器实现

要求

• Node.js 18.x 或更高版本
• npm 9.x 或更高版本
• Claude Desktop（最新版本）

📝 贡献

欢迎贡献！ 请随时提交拉取请求。

1. Fork 存储库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

🧪 测试

TimezoneToolkit 包括一个综合测试脚本，可用于验证 MCP 服务器的功能。 该测试脚本可用于测试本地构建、版本标志、列出所有可用工具、测试特定工具以及在发布后测试 npm 包。

运行测试

# 测试本地构建（默认）
node test-server.js

# 测试特定工具
node test-server.js --tool=calculate_sunrise_sunset

# 列出所有可用工具
node test-server.js --list

# 测试版本标志
node test-server.js --test-version

# 测试已发布的 npm 包（发布后）
node test-server.js --npm

测试脚本将输出有关测试结果的详细信息，包括响应格式是否正确以及内容是否为有效的 JSON。

示例输出

Testing local build...
Running: node /path/to/timezone-toolkit/dist/index.js

Sending request: {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_current_time",
    "arguments": {
      "timezone": "America/New_York"
    }
  }
}

Response: {
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"currentTime\": \"Mar 25, 2025, 9:54 PM\",\n  \"timezone\": \"America/New_York\",\n  \"utcOffset\": \"-04:00\"\n}"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": 1
}
✅ Response format is correct (has content array)
✅ Content is valid JSON: {
  currentTime: 'Mar 25, 2025, 9:54 PM',
  timezone: 'America/New_York',
  utcOffset: '-04:00'
}

✅ Test completed successfully!

🐛 故障排除

常见问题

1. 工具未显示在 Claude Desktop 中

   • 确保服务器已在 Claude Desktop 设置中正确配置
   • 检查 index.js 文件的路径是否正确
   • 重新启动 Claude Desktop

2. 时区计算不正确

   • 验证您是否正在使用有效的 IANA 时区名称（例如，“America/New_York”，而不是“EST”）
   • 检查可能影响计算的夏令时转换

3. 日出/日落计算不起作用

   • 确保纬度和经度值有效（纬度为 -90 到 90，经度为 -180 到 180）
   • 一些极北/南的位置可能存在没有日出/日落的时期

🔒 隐私与安全

TimezoneToolkit 在本地处理所有数据，不会将任何信息发送到外部服务器。 您的时区数据和查询在您的设备上保持私密。

📃 许可证

ISC

👨‍💻 作者

Cicatriz