Time MCP Server

时间 MCP 服务

一个为大模型提供时间相关工具的模型上下文协议（MCP）服务。使用 FastMCP 2.0 构建。

设置

本项目使用 uv 管理 Python 包，并使用 task 运行常用命令。

先决条件

• Python 3.12 或更高版本
• uv - 快速的 Python 包安装器和解析器
• Task - 任务运行器 / 构建工具

安装

1. 克隆仓库
2. 运行设置任务以创建虚拟环境：

   task setup
   

3. 以开发模式安装软件包：

   task install
   

使用方法

运行服务

使用任务运行器运行 MCP 服务：

task run

默认情况下，服务将使用 stdio 传输启动，非常适合与 Claude Desktop 和其他本地 MCP 客户端连接。

命令行选项

你可以配置传输类型和端口：

# Run with stdio transport (default)
python -m time_mcp_server.main --transport stdio

# Run with HTTP transport on port 9000
python -m time_mcp_server.main --transport streamable-http --port 9000

或者使用任务运行器时，可以在 -- 后传递参数：

# Run with stdio transport (default)
task run

# Run with HTTP transport
task run -- --transport streamable-http --port 9000

可用工具

Time MCP Server 为大模型提供以下工具：

1. get_current_time - 获取当前日期和时间

   • 参数：
     • date_format（可选）：日期时间的格式字符串（例如，'%Y-%m-%d %H:%M:%S'）
     • timezone（可选）：时区名称（例如，'Europe/Berlin'、'America/New_York'）。默认为 'Europe/Berlin'
   • 返回：包含 ISO 格式的当前时间、指定格式的时间以及所用时区的字典

2. get_time_components - 获取当前时间的组成部分

   • 参数：
     • timezone（可选）：时区名称（例如，'Europe/Berlin'、'America/New_York'）。默认为 'Europe/Berlin'
   • 返回：包含年、月、日、小时、分钟、秒、微秒、星期几和时区的字典

客户端使用示例

要通过大模型客户端使用此 MCP 服务，请连接到服务端点并调用工具：

import asyncio
from fastmcp import Client

async def main():
    # Connect to the Time MCP Server
    # Make sure to include the root path '/' in the URL
    async with Client("http://localhost:8090/") as client:
        # Get the current time
        result = await client.call_tool("get_current_time", {"date_format": "%Y-%m-%d %H:%M:%S", "timezone": "America/New_York"})
        # Parse the JSON response
        import json
        time_data = json.loads(result[0].text)
        print(time_data)
        # Output: {'iso_time': '2025-05-09T10:27:31.123456-04:00', 'formatted_time': '2025-05-09 10:27:31', 'timezone': 'America/New_York'}
        
        # Get time components
        result = await client.call_tool("get_time_components", {"timezone": "Europe/Berlin"})
        components = json.loads(result[0].text)
        print(components)
        # Output: {'year': 2025, 'month': 5, 'day': 9, 'hour': 16, 'minute': 27, 'second': 31, 'microsecond': 123456, 'weekday': 4, 'timezone': 'Europe/Berlin'}

# Run the async client
asyncio.run(main())

连接到 Claude Desktop

由于 Time MCP Server 现在默认使用 stdio 传输，因此可以轻松连接到 Claude Desktop。设置方法如下：

1. 打开 Claude Desktop
2. 点击顶部栏中的“Claude”菜单（macOS 上），或 Windows 上相应的菜单
3. 选择“Settings...”，然后前往“Developer” > “Edit Config”
4. 将 Time MCP Server 添加到配置文件中：

{
  "mcpServers": {
    "current-time": {
      "command": "/path/to/uv",
      "args": [
        "run", "--directory", "/path/to/time-mcp-server", "python", "-m", "time_mcp_server.main"
      ]
    }
  }
}

请务必将 /path/to/uv 替换为 uv 可执行文件的路径，并将 /path/to/time-mcp-server 替换为项目目录的实际路径。

5. 保存配置文件并重启 Claude Desktop
6. 你应该会在 Claude 输入框的右下角看到一个锤子图标
7. 点击该图标即可查看 Time MCP Server 的工具

现在你可以让 Claude 使用时间工具，例如：

• “现在几点了？”
• “你能告诉我当前日期吗？格式为 YYYY-MM-DD。”
• “今天是星期几？”
• “纽约现在几点？”
• “东京时区现在几点？”

项目结构

项目采用以下结构组织：

src/time_mcp_server/
├── __init__.py       # Package initialization
├── main.py          # Command-line interface and entry point
├── server.py        # MCP server configuration
└── tools.py         # Time tool implementations

tests/
└── test_client.py   # Tests for the time tools

开发

• 格式化代码：task format
• 检查并修复 lint 问题：task check
• 运行测试：task test

测试

本项目包含演示如何将 Time MCP Server 用作客户端的测试。测试使用 FastMCP 的内存客户端直接连接到服务，无需网络连接。

# Example of using the FastMCP client to connect to the server
from fastmcp import Client
from time_mcp_server.server import mcp  # Import the MCP server instance

async with Client(mcp) as client:
    # List available tools
    tools = await client.list_tools()
    
    # Call the get_current_time tool
    result = await client.call_tool("get_current_time", {"date_format": "%Y-%m-%d %H:%M:%S", "timezone": "Europe/Berlin"})
    text_content = result[0]
    
    # Parse the JSON response
    import json
    time_data = json.loads(text_content.text)
    print(time_data)

运行测试：

task test