timer-mcp-server

xueli-sherryli/timer-mcp-server

3.2

If you are the rightful owner of timer-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Timer MCP Server is a specialized server for handling time-related operations, offering tools for time conversions, calculations, and timezone management.

Tools
6
Resources
0
Prompts
0

Timer MCP Server

This project is an MCP (Model Context Protocol) server designed for time-related operations. It provides a suite of tools for handling time conversions, calculations, and timezone management.

[!NOTE] This project was entirely generated by Gemini, with only modifications made to the runtime environment.

Quickstart

Using uv

  1. Create virtual environment and sync dependencies:

    uv venv
uv pip sync

  2. Run the server:

    uv run main.py

    The server will run on port 8000 by default.

Using docker

  1. Build and run the container: 
    docker-compose up --build -d

Configuration

The server runs on port 8000 by default. If you need to change the port, you can modify it directly in the docker-compose.yml file. For example, to map to port 8080 on the host:

ports:
  - "8080:8000"

Tools

The server runs in sse (Server-Sent Events) mode and provides the following tools:

1. get_current_time

Gets the current time.

Input:

  • timezone (string, optional): IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to 'Asia/Shanghai' if invalid or not provided.

Output:

  • timestamp (int64): The current Unix timestamp.
  • timezone (string): The timezone used for the conversion.
  • current_time (string): The formatted time string (YYYY-MM-DD HH:MM:SS).

2. convert_timestamp_to_time

Converts a Unix timestamp to a human-readable time string.

Input:

  • timestamp (int64): The Unix timestamp to convert.
  • timezone (string, optional): IANA timezone name. Defaults to 'Asia/Shanghai'.

Output:

  • timezone (string): The timezone used for the conversion.
  • time (string): The formatted time string (YYYY-MM-DD HH:MM:SS).

3. convert_time_to_timestamp

Converts a human-readable time string to a Unix timestamp.

Input:

  • time (string): The time string to convert (format: YYYY-MM-DD HH:MM:SS).
  • timezone (string, optional): IANA timezone name. Defaults to 'Asia/Shanghai'.

Output:

  • timezone (string): The timezone used for the conversion.
  • timestamp (int64): The resulting Unix timestamp.

4. time_difference

Calculates the difference between two timestamps.

Input:

  • start_timestamp (int64): The start time as a Unix timestamp.
  • end_timestamp (int64): The end time as a Unix timestamp.

Output:

  • time_difference (int64): The difference in seconds (can be positive or negative).

5. time_difference_caculate

Breaks down a time difference (in seconds) into years, months, days, etc.

Input:

  • time_difference (int64): The time difference in seconds to calculate.
  • mode (string, optional): Accepts 'p' for progressive or 's' for separate calculation. Defaults to 'p'.
    • p (progressive): Calculates years, then months from the remainder, then days, and so on.
    • s (separate): Calculates the total duration in each unit independently.

Output: A JSON object with the following fields:

  • time_difference (int64): The original time difference in seconds.
  • years (float)
  • months (float)
  • days (float)
  • hours (float)
  • minutes (float)
  • seconds (float)

6. get_day_of_week

Calculates the day of the week from a Unix timestamp.

Input:

  • timestamp (int64): The Unix timestamp.

Output:

  • timestamp (int64): The original Unix timestamp.
  • day_of_week (string): The full name of the day of the week (e.g., "Monday").

Timer MCP 服务器

本项目是一个专为时间相关操作设计的 MCP (模型上下文协议) 服务器。它提供了一套用于处理时间转换、计算和时区管理的工具。

[!NOTE] 本项目完全由 Gemini 生成，仅对运行环境进行了修改。

快速开始

使用 uv

  1. 创建虚拟环境并同步依赖:

    uv venv
uv pip sync

  2. 运行服务器:

    uv run main.py

    服务器默认在 8000 端口上运行。

使用 docker

  1. 构建并运行容器: 
    docker-compose up --build -d

配置

服务器默认在 8000 端口上运行。如果您需要更改端口，可以直接修改 docker-compose.yml 文件。例如，要映射到主机的 8080 端口：

ports:
  - "8080:8000"

工具

该服务器以 sse (服务器发送事件) 模式运行，并提供以下工具：

1. get_current_time

获取当前时间。

输入:

  • timezone (string, 可选): IANA 时区名称 (例如, 'America/New_York', 'Europe/London')。如果输入无效或未提供，则默认为 'Asia/Shanghai'。

输出:

  • timestamp (int64): 当前的 Unix 时间戳。
  • timezone (string): 用于转换的时区。
  • current_time (string): 格式化的时间字符串 (YYYY-MM-DD HH:MM:SS)。

2. convert_timestamp_to_time

将 Unix 时间戳转换为人类可读的时间字符串。

输入:

  • timestamp (int64): 需要转换的 Unix 时间戳。
  • timezone (string, 可选): IANA 时区名称。默认为 'Asia/Shanghai'。

输出:

  • timezone (string): 用于转换的时区。
  • time (string): 格式化的时间字符串 (YYYY-MM-DD HH:MM:SS)。

3. convert_time_to_timestamp

将人类可读的时间字符串转换为 Unix 时间戳。

输入:

  • time (string): 需要转换的时间字符串 (格式: YYYY-MM-DD HH:MM:SS)。
  • timezone (string, 可选): IANA 时区名称。默认为 'Asia/Shanghai'。

输出:

  • timezone (string): 用于转换的时区。
  • timestamp (int64): 转换后的 Unix 时间戳。

4. time_difference

计算两个时间戳之间的差值。

输入:

  • start_timestamp (int64): 作为起始时间的 Unix 时间戳。
  • end_timestamp (int64): 作为结束时间的 Unix 时间戳。

输出:

  • time_difference (int64): 相差的秒数 (可为正或负)。

5. time_difference_caculate

将一个时间差 (以秒为单位) 分解为年、月、日等单位。

输入:

  • time_difference (int64): 需要计算的时间差 (秒)。
  • mode (string, 可选): 接受 'p' (累进计算) 或 's' (单独计算)。默认为 'p'。
    • p (累进): 先计算年，然后从余数中计算月，再计算日，依此类推。
    • s (单独): 独立地计算各个单位下的总时长。

输出: 一个包含以下字段的 JSON 对象：

  • time_difference (int64): 原始的时间差 (秒)。
  • years (float)
  • months (float)
  • days (float)
  • hours (float)
  • minutes (float)
  • seconds (float)

6. get_day_of_week

根据 Unix 时间戳计算星期几。

输入:

  • timestamp (int64): Unix 时间戳。

输出:

  • timestamp (int64): 原始的 Unix 时间戳。
  • day_of_week (string): 星期几的全名 (例如, "Monday")。