MCP Simple Timeserver

What andybrandt/mcp-simple-timeserver MCP server does

andybrandt/mcp-simple-timeserver MCP server adds time and calendar operations to an MCP-compatible client. It can report the client machine's local time, weekday, and timezone, or retrieve UTC from an NTP time server. The server also supports location-aware time queries using a city, country, IANA timezone, or UTC offset.

The get_current_time tool can return UTC offset and daylight-saving information for a requested location. It also accepts calendar conversions for Unix timestamps, ISO week dates, Hijri, Japanese Era, Hebrew, and Persian formats. Location precedence is timezone first, then city, then country.

Time calculations are handled by calculate_time_distance, which can measure countdowns or elapsed time in several units. It also supports business-day counting and can exclude public holidays when a country or city is supplied. The holiday tools use Nager.Date for public holidays and OpenHolidaysAPI for school-holiday information.

How it works

The server exposes six MCP tools: get_local_time, get_utc, get_current_time, calculate_time_distance, get_holidays, and is_holiday. get_holidays returns public holidays for a country and can optionally include school vacation periods. is_holiday checks a date and can use a city to narrow regional school-holiday results.

NTP-backed time is used by every tool except get_local_time. If an NTP server cannot be reached, the server uses local server time and indicates that fallback in the response. Holiday coverage is listed as approximately 119 countries for public holidays and 36 countries for school holidays.

For business-day calculations, the server counts Monday through Friday as full date-based days and treats the endpoints as inclusive. Time of day is ignored in that mode, and holidays are excluded only when they fall on weekdays.

Setup and configuration

Install the Python package with pip install mcp-simple-timeserver. A local MCP client can start and communicate with the server using the Python module entry point:

{
  "mcpServers": {
    "simple-timeserver": {
      "command": "python",
      "args": ["-m", "mcp_simple_timeserver"]
    }
  }
}

On Windows, the configuration may need the full path to the Python executable. The andybrandt/mcp-simple-timeserver MCP server also includes a network-hostable web-server variant, with deployment instructions in the project's web deployment guide. A hosted instance is available at https://mcp.andybrandt.net/timeserver for clients that support MCP connections to that endpoint.

Tools and capabilities

• Read local machine time, weekday, and timezone.
• Retrieve UTC from NTP, with local-time fallback when NTP is unavailable.
• Convert current time by city, country, timezone, or UTC offset.
• Return Unix, ISO week, Hijri, Japanese, Hebrew, or Persian calendar values.
• Calculate elapsed time, countdowns, and business days.
• List or check public holidays and, where available, school holidays.

Limitations and notes

The quality and coverage of holiday results depend on the external Nager.Date and OpenHolidaysAPI data sources. School-holiday support is available for fewer countries than public-holiday support. Regional school-holiday filtering requires a city for locations where schedules vary by administrative region.

The server does not provide message timestamps from the MCP client itself; it supplies current-time and date information through its tools. When NTP is unavailable, returned time is based on the local server clock rather than an NTP measurement.