mcp-simple-timeserver

mcp-simple-timeserver is a Python-based MCP server that provides a set of time-related tools to help Claude (and other MCP clients) obtain accurate time information and time-based utilities. The server exposes tools such as get_local_time, get_utc, get_current_time, calculate_time_distance, get_holidays, and is_holiday. Most of these rely on NTP when available to ensure precise timing, with a graceful fallback to local server time if NTP cannot be reached. The get_current_time tool supports location parameters (city, country, timezone) and optional calendar formats to return time in various calendars, while the holiday and distance tools enable calendar-aware calculations across many countries. Together, these tools fix gaps in time awareness for chat interactions and allow applications to perform time-based calculations reliably.

To use the tools, run the MCP server and connect a client (such as Claude Desktop or other MCP-aware clients) configured to the simple-timeserver endpoint. Commands are invoked by the client against the server and return structured time data and calendar-related results. For example, you can query the current time in a specific timezone or city, compute the duration between two dates, check whether a date is a holiday in a given country, or fetch public holidays for a country. The location-aware features for get_current_time let you specify timezone or city/country to obtain localized results, including DST status and UTC offsets.

The Web Server variant is also available for deployment as a standalone web server, enabling network-hosted usage without Claude Desktop. See the Web Deployment Guide for setup details if you prefer hosting the service as a web endpoint.

Prerequisites:

• Python 3.8+ installed on your system
• Pip available in your Python environment
• Optional: Smithery if you want an automated install flow via Smithery (not required for manual usage)

Manual installation steps:

1. Install the MCP Simple Timeserver package from PyPI:

pip install mcp-simple-timeserver

2. Configure the MCP client to load this server. The example configuration for Claude Desktop (MCP client) is:

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

3. If you are on Windows, determine the path to Python and adjust the command accordingly, e.g.:

"mcpServers": {
  "simple-timeserver": {
    "command": "C:\\Python\\Python311\\python.exe",
    "args": ["-m", "mcp_simple_timeserver"]
  }
}

4. Start the server via the MCP client integration or by running the module directly in a test environment (if you want to run manually):

python -m mcp_simple_timeserver

5. If you prefer the Smithery installation flow, you can use:

npx -y @smithery/cli install mcp-simple-timeserver --client claude

6. For deployment as a standalone web server, follow the Web Deployment Guide referenced in the repository.

Notes and tips:

• The server primarily provides time utilities; most tools rely on NTP when available. If NTP is unavailable, the server uses local time but logs a notice about the fallback.
• The get_current_time tool supports location-based queries with priority: timezone > city > country. When a location is provided, the response includes local time, timezone info, UTC offset, and DST status.
• The calculate_time_distance tool can compute durations with options for business days and holidays. You can specify city/country to apply regional holiday calendars.
• For holiday data, the service uses Nager.Date API (public holidays) and OpenHolidaysAPI (school holidays). Availability varies by country.
• If you deploy via the web server variant, you can access the timeserver through a network endpoint and integrate it with Claude or other MCP clients using the documented path (or the provided deployment guide).
• Ensure your runtime environment has network access for NTP and holiday data lookups when using full features.