MCP Simple Timeserver

1[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/andybrandt-mcp-simple-timeserver-badge.png)](https://mseep.ai/app/andybrandt-mcp-simple-timeserver)
2 
3# MCP Simple Timeserver
4[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/andybrandt/mcp-simple-timeserver)](https://archestra.ai/mcp-catalog/andybrandt__mcp-simple-timeserver)
5[![smithery badge](https://smithery.ai/badge/mcp-simple-timeserver)](https://smithery.ai/server/mcp-simple-timeserver)
6 
7*One of the strange design decisions Anthropic made was depriving Claude of timestamps for messages sent by the user in claude.ai or current time in general. Poor Claude can't tell what time it is! `mcp-simple-timeserver` is a simple MCP server that fixes that.*
8 
9## Available Tools
10 
11This server provides the following tools:
12 
13| Tool | Description |
14|------|-------------|
15| `get_local_time` | Returns the current local time, day of week, and timezone from the user's machine |
16| `get_utc` | Returns accurate UTC time from an [NTP time server](https://en.wikipedia.org/wiki/Network_Time_Protocol) |
17| `get_current_time` | Returns current time with optional location, timezone, and calendar conversions |
18| `calculate_time_distance` | Calculates duration between two dates/times (countdowns, elapsed time) |
19| `get_holidays` | Returns public holidays (and optionally school holidays) for a country |
20| `is_holiday` | Checks if a specific date is a holiday in a given country or city |
21 
22All tools (except `get_local_time`) use accurate time from NTP servers. If NTP is unavailable, they gracefully fall back to local server time with a notice.
23 
24### Location Support via `get_current_time`
25 
26The `get_current_time` tool supports location parameters to get local time anywhere in the world:
27 
28| Parameter | Description | Example |
29|-----------|-------------|---------|
30| `city` | City name (primary use case) | `"Warsaw"`, `"Tokyo"`, `"New York"` |
31| `country` | Country name or ISO code | `"Poland"`, `"JP"`, `"United States"` |
32| `timezone` | IANA timezone or UTC offset | `"Europe/Warsaw"`, `"+05:30"` |
33 
34Priority: `timezone` > `city` > `country`. When location is provided, the response includes local time, timezone info, UTC offset, and DST status.
35 
36If today is a public holiday at the specified location, it will be shown in the output.
37 
38### Calendar Support via `get_current_time`
39 
40The `get_current_time` tool also accepts an optional `calendar` parameter with a comma-separated list of calendar formats:
41 
42| Calendar | Description |
43|----------|-------------|
44| `unix` | Unix timestamp (seconds since 1970-01-01) |
45| `isodate` | ISO 8601 week date (e.g., `2026-W03-6`) |
46| `hijri` | Islamic/Hijri lunar calendar |
47| `japanese` | Japanese Era calendar (returns both English and Kanji) |
48| `hebrew` | Hebrew/Jewish calendar (returns both English and Hebrew, includes holidays) |
49| `persian` | Persian/Jalali calendar (returns both English and Farsi) |
50 
51Example: `get_current_time(city="Tokyo", calendar="japanese")` returns Tokyo local time with Japanese Era calendar.
52 
53### Time Distance Calculation via `calculate_time_distance`
54 
55Calculate duration between two dates or times:
56 
57| Parameter | Description | Example |
58|-----------|-------------|---------|
59| `from_date` | Start date (ISO 8601 or "now") | `"2025-01-15"`, `"now"` |
60| `to_date` | End date (ISO 8601 or "now") | `"2025-12-31"`, `"2025-06-01T17:00:00"` |
61| `unit` | Output format | `"auto"`, `"days"`, `"weeks"`, `"hours"`, `"minutes"`, `"seconds"` |
62| `business_days` | Count only Mon-Fri (date-based, inclusive) | `true` |
63| `exclude_holidays` | Also exclude public holidays (requires country/city) | `true` |
64 
65Location parameters (`city`, `country`, `timezone`) can also be used to specify timezone context.
66 
67When `business_days=true`, time-of-day is ignored and dates are counted as full days (inclusive endpoints).
68The `unit` parameter is ignored in this mode. Holidays are excluded only when they fall on weekdays.
69 
70Example: `calculate_time_distance(from_date="now", to_date="2025-12-31")` returns a countdown to New Year's Eve.
71Example: `calculate_time_distance(from_date="2026-01-26", to_date="2026-01-30", business_days=true, exclude_holidays=true, city="Sydney")` returns the number of business days in that range.
72 
73### Holiday Information via `get_holidays` and `is_holiday`
74 
75Get public and school holiday information for ~119 countries:
76 
77**`get_holidays`** parameters:
78 
79| Parameter | Description | Example |
80|-----------|-------------|---------|
81| `country` | Country name or ISO code (required) | `"Poland"`, `"DE"`, `"United States"` |
82| `year` | Year to get holidays for (default: current year) | `2026` |
83| `include_school_holidays` | Include school vacation periods | `true` |
84 
85**`is_holiday`** parameters:
86 
87| Parameter | Description | Example |
88|-----------|-------------|---------|
89| `country` | Country name or ISO code | `"Poland"`, `"US"` |
90| `city` | City name for region-specific info | `"Warsaw"`, `"Munich"` |
91| `date` | Date to check in ISO format (default: today) | `"2026-01-01"` |
92 
93**Regional School Holidays**: When using the `city` parameter with `is_holiday`, school holidays are filtered to show only those affecting the specific region. This is particularly useful in countries where school holidays vary by region (e.g., Polish voivodeships, German Bundesländer, Spanish autonomous communities).
94 
95Example: `is_holiday(city="Warsaw", date="2026-01-19")` returns school holiday information specific to the Mazowieckie voivodeship.
96 
97**Data Sources**:
98- Public holidays: [Nager.Date API](https://date.nager.at/) (119 countries)
99- School holidays: [OpenHolidaysAPI](https://openholidaysapi.org/) (36 countries, mostly European)
100 
101## Installation
102 
103### Installing via Smithery
104 
105To install Simple Timeserver for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-simple-timeserver):
106 
107```bash
108npx -y @smithery/cli install mcp-simple-timeserver --client claude
109```
110 
111### Manual Installation
112First install the module using:
113 
114```bash
115pip install mcp-simple-timeserver
116 
117```
118 
119Then configure in MCP client - the [Claude desktop app](https://claude.ai/download).
120 
121Under Mac OS this will look like this:
122 
123```json
124"mcpServers": {
125  "simple-timeserver": {
126    "command": "python",
127    "args": ["-m", "mcp_simple_timeserver"]
128  }
129}
130```
131 
132Under Windows you have to check the path to your Python executable using `where python` in the `cmd` (Windows command line). 
133 
134Typical configuration would look like this:
135 
136```json
137"mcpServers": {
138  "simple-timeserver": {
139    "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
140    "args": ["-m", "mcp_simple_timeserver"]
141  }
142}
143```
144 
145## Web Server Variant
146 
147This project also includes a network-hostable version that can be deployed as a standalone web server. For instructions on how to run and deploy it, please see the [Web Server Deployment Guide](WEB_DEPLOYMENT.md).
148 
149Or you can simply use my server by adding it under https://mcp.andybrandt.net/timeserver to Claude and other tools that support MCP.
150