# TimezoneDB MCP > TimezoneDB manages global time data, allowing your AI agent to audit offsets and retrieve accurate local times for any zone. It handles Daylight Saving Time (DST) rules and converts coordinates into precise time stamps. This server gives you an authoritative source for worldwide clock data, so your workflows never rely on manual lookups or outdated calendars. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** timezone-conversion, world-clock, daylight-saving, offset-lookup, global-time, regional-data ## Description Look, you don't wanna be relying on guesswork when dealing with global time. The clock changes everywhere, and old calendars are useless. This server gives your AI client an authoritative source for worldwide clock data, so you never have to manually look up offsets or guess what Daylight Saving Time (DST) rules mean in another hemisphere. It handles the whole mess of coordinate conversions and zone definitions. Before anything else, you'll want to run `check_api_status`. This single call confirms if the entire TimezoneDB server is live and responding correctly. You gotta make sure it's up before your agent runs any mission-critical queries; otherwise, all that work hits a dead end. When you need context—say, you just want to know what time zones exist in Canada, but you don't know the specific city or date—you use `list_timezones`. This tool returns an exhaustive list of every supported timezone. You can even narrow it down by country if you only care about one region. If you already know the zone identifier—like 'Europe/Paris' or 'America/Los_Angeles'—you jump straight to `get_time_by_zone`. This call doesn't just spit out a time. It returns the current local time *and* all the necessary metadata for that specific timezone string, giving you full details on its offset and structure. Sometimes, you don't know the zone ID; you only have coordinates—say, latitude 34.05 and longitude -118.24. That’s when you use `get_time_by_location`. You plug in those exact geographic coordinates, and your agent gets back the precise current local time for that spot on Earth, along with the correct timezone ID to go with it. Here's where things get tricky: DST changes. If you schedule a meeting across different zones, you need to know if Daylight Saving Time is active right now. You run `get_dst_status` and tell it the specific time zone. It checks whether or not that region is currently observing DST rules, which is critical for accurate scheduling and avoiding off-by-an-hour errors. Every tool here works together to solve timing problems. For example, if you're building a system that needs to calculate an offset between two points on Earth, your agent first uses `list_timezones` to confirm both zones are supported. It then might use `get_dst_status` for each zone to account for any seasonal shifts before finally running `get_time_by_location` with the coordinates of one point and cross-referencing it against a time pulled from `get_time_by_zone` at another location. This gives you an audited, reliable time difference. This server eliminates the need to consult external APIs or rely on hardcoded offsets that fail when DST kicks in. You're working with real-time data management for over 400 worldwide zones. It ensures your agent always knows the accurate local time based on whether you provide a clean zone string, raw coordinates, or just want to verify if the whole damn thing is operational. ## Tools ### check_api_status Checks if the TimezoneDB API is operational and available for use. ### get_dst_status Determines whether Daylight Saving Time is currently active in a specific time zone. ### get_time_by_location Gets the current time by taking specific geographic latitude and longitude coordinates. ### get_time_by_zone Retrieves the current time and full details for a specified timezone string (e.g., 'America/Chicago'). ### list_timezones Lists all supported timezones, allowing you to optionally filter the list by country. ## Prompt Examples **Prompt:** ``` What is the current time in 'Asia/Tokyo' using TimezoneDB? ``` **Response:** ``` I've retrieved the current time for Tokyo. It is currently 10:30 PM (GMT+9). Daylight saving is not active. Would you like the details for another zone? ``` **Prompt:** ``` Check time for latitude 40.7128, longitude -74.0060. ``` **Response:** ``` I've identified the location as New York, United States (America/New_York). The current time is 8:30 AM (GMT-5). Would you like to check the DST status? ``` **Prompt:** ``` List all timezones in 'Brazil'. ``` **Response:** ``` I've scanned the zones for Brazil. It includes several timezones, such as America/Sao_Paulo (GMT-3) and America/Manaus (GMT-4). I can provide the current time for any of these. ``` ## Capabilities ### Check API health Confirms if the TimezoneDB server is currently operational and responding correctly. ### Get time from coordinates Takes latitude and longitude to return the current, accurate local time for that exact spot on Earth. ### Get time by zone identifier Retrieves the current time and metadata using a standard timezone string (like 'Europe/London'). ### Audit Daylight Saving Time Checks if DST is currently active for a specified time zone, helping prevent scheduling errors. ### List and filter all zones Returns an exhaustive list of supported timezones, optionally filtering the results by country. ## Use Cases ### Scheduling a Global Standup A manager needs to find an overlap window for meetings across London and Sydney. They ask their agent: 'What's the best time next week?' The agent runs `list_timezones` to confirm valid IDs, then uses `get_time_by_zone` for both zones, presenting a viable common working hour. ### Debugging Geo-Service Time Drift A developer's service fails when moving between two continents. They use `get_time_by_location` twice—once at coordinates 34, -118 and once at 51, 0. The resulting time difference confirms the local offset error in their code logic. ### Validating Data Inputs A data team needs to verify if a historical dataset includes zones that observe DST. They run `get_dst_status` for a list of candidate zones, ensuring the time calculation will be accurate even when rules change. ### Building an International App Feature An app developer needs to display local time on a map widget. They use `get_time_by_location` with the user's current GPS coordinates, ensuring the displayed time is always correct without needing manual timezone input. ## Benefits - Stop manually checking DST rules. The `get_dst_status` tool instantly confirms if daylight saving is active in a given region, preventing scheduling conflicts before they happen. - You don't have to guess the timezone format. Use `list_timezones` to query all supported zones and filter them by country name, ensuring you use the correct ID for your queries. - Need time right now? Instead of remembering a zone string, just give coordinates (lat/lon) to `get_time_by_location`. It figures out the local time automatically. - The agent handles the complexity. You ask: 'What's 2 PM in New York?', and the server uses `get_time_by_zone` to deliver a precise, formatted answer without you writing any code. - Built-in resilience. Before running a major query, always run `check_api_status`. This verifies the entire service is up, saving you time debugging connection errors. ## How It Works The bottom line is that you feed the API key to your client once, and then your agent handles all global time logic for you. 1. Subscribe to TimezoneDB on Vinkius and enter your API Key into your AI client. 2. Ask your agent for global time details (e.g., 'What's the time in Sydney?'). 3. The agent calls the appropriate tool (`get_time_by_zone`) using your key, retrieves the data, and gives you a natural language answer. ## Frequently Asked Questions **How do I check if DST is active using get_dst_status?** You simply pass the zone identifier (e.g., 'America/Denver') to `get_dst_status`. The tool returns a clear boolean status and explains the rules in use for that specific time zone. **What's the difference between get_time_by_location and get_time_by_zone?** Use `get_time_by_zone` when you know the IANA string (like 'Europe/Paris'). Use `get_time_by_location` when you only have GPS coordinates, forcing the agent to figure out the zone first. **Can I use list_timezones to find all zones in Japan?** Yes. You run `list_timezones`, optionally filtering by 'Japan'. The tool returns a structured list of every supported timezone within that country, helping you audit regional variations. **What should I do if my time query fails? Should I use check_api_status first?** Yeah, that's the safest bet. Always call `check_api_status` first. If it returns success, you know the problem is with your input (like a bad zone ID) and not the service itself. **Is TimezoneDB better than using built-in system time functions?** Yes, because this server uses authoritative, globally maintained data. System functions rely on local machine settings; TimezoneDB is an external, verifiable source for complex global rules. **What's the best way to authenticate when using `get_time_by_zone`?** The system requires you to pass your unique API key in the designated header parameter during all calls. Once authenticated, your AI client can reliably fetch current time and offset details for any zone name. **If I need coordinates and offsets across many zones, how does `list_timezones` help me gather all metadata?** `list_timezones` first gives you the full list of supported zone IDs. You then iterate through that resulting array, passing each unique ID to other tools like `get_time_by_location` to pull specific coordinates or offsets. **If my queries exceed the usage limit using `get_time_by_location`, how do I handle the throttling?** The server sends a standard HTTP 429 error code when you hit your rate limit. You need to implement exponential backoff in your client script and wait for the reset window specified in the API response headers. **How do I find my TimezoneDB API Key?** Log in to your [**TimezoneDB account**](https://timezonedb.com/register), and you will find your API Key on the main page. Copy and paste it below. **Does the agent support searching by city?** While the primary tools use zone strings or coordinates, you can use `list_timezones` to find the correct zone name for a specific country. **Can the agent check if DST is active?** Yes. The `get_dst_status` tool returns a boolean value identifying if daylight saving time is currently being observed in the specified zone.