TimezoneToolkit MCP Server

可用工具

工具	描述
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 服务，请使用以下命令：

npx -y @cicatriz/timezone-toolkit@latest

特定客户端的安装方式

Cursor

要将此服务添加到 Cursor IDE：

1. 前往 Cursor Settings > MCP
2. 点击 + Add new Global MCP Server
3. 将以下配置添加到全局 .cursor/mcp.json 文件中：

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

有关详情，请参阅 Cursor 文档。

Windsurf

要通过 Cascade 设置 MCP，请前往 Windsurf - Settings > Advanced Settings，或使用 Command Palette > Open Windsurf Settings Page。

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

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

Cline

通过 Cline MCP Server 设置，将以下 JSON 手动添加到 cline_mcp_settings.json：

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

Roo Code

在 Roo Code 设置中点击 Edit MCP Settings，或使用 VS Code 命令面板中的 Roo Code: Open MCP Config 命令，即可访问 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 文档。

命令行

也可以运行以下命令，通过命令行启动：

npx -y @cicatriz/timezone-toolkit@latest

其他安装方式

从 npm 安装

# Install globally from npm
npm install -g @cicatriz/timezone-toolkit

# Run the server
timezone-toolkit

手动安装

# Clone the repository
git clone https://github.com/Cicatriiz/timezone-toolkit.git
cd timezone-toolkit

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
node dist/index.js

💬 在 Claude Desktop 中使用

安装后，即可在 Claude Desktop 中使用 TimezoneToolkit：

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

🔗 API 访问

TimezoneToolkit 还提供 RESTful API，无需 Claude Desktop 即可访问其功能：

启动 API 服务

# Using 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": "Tuesday, December 26, 2023, 4:30:00 AM Japan Standard Time",
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "timeDifference": "+14 hours"
}

2. get_current_time

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

参数：

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

示例：

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

响应：

{
  "currentTime": "Monday, March 25, 2025, 10:15:30 PM British Summer Time",
  "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 AM",
  "sunset": "08:35:13 PM",
  "civilTwilight": {
    "dawn": "05:17:22 AM",
    "dusk": "09:06:02 PM"
  },
  "nauticalTwilight": {
    "dawn": "04:38:43 AM",
    "dusk": "09:44:41 PM"
  },
  "astronomicalTwilight": {
    "dawn": "03:52:50 AM",
    "dusk": "10:30:34 PM"
  },
  "dayLength": "14 hours 47 minutes",
  "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": "Full Moon",
  "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 hours",
  "currentTimeFrom": "3/25/2025, 6:15 PM",
  "currentTimeTo": "3/26/2025, 8:15 AM",
  "hoursDifference": 14,
  "minutesDifference": 0,
  "totalMinutesDifference": 840,
  "direction": "ahead"
}

6. list_timezones

列出可用的 IANA 时区，可按区域筛选。

参数：

• region（可选）：按区域筛选时区（例如，'America'、'Europe'、'Asia'）

示例：

{
  "region": "Europe"
}

响应：

{
  "timezones": [
    {
      "timezone": "Europe/Amsterdam",
      "currentTime": "3/25/2025, 11:15 PM",
      "offset": "+02:00"
    },
    {
      "timezone": "Europe/Berlin",
      "currentTime": "3/25/2025, 11:15 PM",
      "offset": "+02:00"
    },
    // Additional European timezones...
  ],
  "count": 7,
  "region": "Europe"
}

7. calculate_countdown

计算距离指定日期／事件的剩余时间。

参数：

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

示例：

{
  "targetDate": "2025-12-31T23:59:59",
  "timezone": "UTC",
  "title": "New Year's Eve"
}

响应：

{
  "title": "New Year's Eve",
  "targetDate": "2025-12-31T23:59:59.000Z",
  "formattedTargetDate": "Wednesday, December 31, 2025, 11:59:59 PM GMT",
  "currentDate": "2025-03-25T18:15:30.000Z",
  "timezone": "UTC",
  "isPast": false,
  "countdown": "9 months, 6 days, 5 hours, 44 minutes, 29 seconds",
  "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（最新版本）

📝 贡献

欢迎贡献！请随时提交 Pull Request。

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. 创建 Pull Request

🧪 测试

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

运行测试

# Test the local build (default)
node test-server.js

# Test a specific tool
node test-server.js --tool=calculate_sunrise_sunset

# List all available tools
node test-server.js --list

# Test the version flag
node test-server.js --test-version

# Test the published npm package (after publishing)
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