Plan Meetings Across Time Zones with findtime.io

findtime.io helps distributed teams compare time zones, spot overlapping work hours, and choose fair meeting times. Select two or more cities to see local times, UTC offsets, and Daylight Saving status, then pick a window that avoids after-hours.

We use the IANA time zone database and update automatically. Toggle 12/24-hour formats, copy a link to share, and explore city pages for detailed time zone information.

How to use findtime.io

  1. Select the cities you want to compare
  2. Review current times and overlapping hours
  3. Choose a fair meeting slot and share the link
findtime.io
Popular Cities
Popular Pairs
findtime.io5:24:06 AM — Wed, 3/25/26
Search docs…API Keys
MCP

findtime.io
MCP Docs for Apps, IDEs, and Agents

Install the published @findtime/mcp-server MCP server in Cursor, Codex, or Claude and call the same production-backed time intelligence surface that powers the Time API and findtime.io.

This page covers installation, verification, and troubleshooting for Cursor, Codex, and Claude, plus the current MCP tool surface and recommended smoke tests.

Distribution: Install from npm, inspect the source on GitHub, or open the public listing in the Official MCP Registry.

Production parity

The MCP server proxies time-api.findtime.io directly so apps and agents stay on one truth surface.

Published install path

Use npx -y @findtime/mcp-server in client config. A repo checkout is not required.

Agent-native tools

The tool surface covers current time, DST, conversion, overlap, meeting finding, and deterministic location search.

Debuggable

We document the config files, exact prompts, and startup logs that mattered when things failed.

MCP

Parity with findtime.io API

The MCP server is a thin adapter over the production Time API. Current time, DST, conversion, overlap, meeting search, and location resolution should return the same answers through MCP and the API for the same inputs.

Expect the following:
  • MCP results should match the live API for the same inputs.
  • A working installation should call the MCP tool directly.
  • If MCP startup fails, fix the client configuration before trusting any fallback output.
MCP

Behavior and retry rules

MCP returns the API payload plus a small amount of adapter metadata so agents can retry deterministically instead of guessing.

What to expect:
  • search_timezones treats countryCode as a ranking hint. When you supply a hint, the MCP result includes primaryMatch and countryFilteredResults so agents do not assume every returned row matches the hint.
  • get_current_time is best with a city, exact timezone, or a location resolved from search_timezones. Exact country-name inputs now resolve directly for single-zone countries and return explicit ambiguity for countries with multiple timezones.
  • Abbreviations such as IST are often ambiguous. Use search_timezones first or pair the query with a region or country when you need one deterministic answer.
  • MCP tool errors keep a consistent shape: HTTP status, request URL, and the parsed API error body are included in the structured result so the client can surface the exact failure.
MCP

Setup by client

Select your client below. The config snippet, verification prompt, and troubleshooting guidance update with the selected platform.

Before you start:
  • Create a developer key first from /developers/keys/.
  • You usually do not need to run a terminal command during setup. The MCP client runs npx -y @findtime/mcp-server for you after you save the config and restart the client.
  • Install Node 20 or newer first so the client can run npx.
  • Use npx -y @findtime/mcp-server in the MCP config. A repo checkout is not required.
  • The package is published on npm and listed in the Official MCP Registry at io.github.hkchao/findtime-mcp-server.
  • Point the server at https://time-api.findtime.io or omit the base URL to use the default.
  • After changing MCP config, fully restart the client before testing again.

Active file

~/.cursor/mcp.jsonCursor

Edit this file for the selected client.

mcp.json
{
  "mcpServers": {
    "findtime": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_MCP_CLIENT_TYPE": "cursor",
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY",
        "FINDTIME_MCP_INSTRUMENTATION_ENABLED": "false"
      }
    }
  }
}
Cursor setup checklist:
  • Confirm which Cursor config is active. If you already have a global MCP config, Cursor may be reading `~/.cursor/mcp.json` instead of a repo-local `.cursor/mcp.json`.
  • Use `npx` so Cursor installs and runs `@findtime/mcp-server` directly. A repo checkout is not required.
  • Keep Cursor Settings open with the Output pane visible before reconnecting so you can watch the MCP startup logs in real time.
  • After saving the config, reload Cursor so it recreates the stdio process with the new values.
MCP

Testing and smoke prompts

Use these prompts to verify that the client is making native MCP tool calls. If the client searches the repo or runs local Node code instead, treat that as fallback behavior and continue debugging the MCP setup.

Verification only:Use the explicit Use the findtime MCP tool ... phrasing during setup so you can confirm the client is calling the MCP server directly. After that succeeds, switch back to normal natural-language prompts.
Cursor smoke test
Use the findtime MCP tool get_current_time for city "Tokyo" with countryCode "JP".
Additional smoke tests
Use the findtime MCP tool get_current_time for city "Tokyo" with countryCode "JP".
Use the findtime MCP tool get_api_diagnostics.
Use the findtime MCP tool search_timezones for "Victoria" with countryCode "CA".
Use the findtime MCP tool get_dst_schedule for timezone "America/New_York".
Use the findtime MCP tool get_dst_schedule for timezone "Europe/London" with year 2026.
Use the findtime MCP tool get_dst_schedule for timezone "Europe/London" with at "2025-03-22T12:00:00Z".
Use the findtime MCP tool convert_time from "New York" to ["London","Tokyo"] at time "9:00 AM" on date "2026-03-10".
Use the findtime MCP tool find_meeting_time for locations ["Tokyo","Cairo","New York"] with countryCodes ["JP","EG","US"] on date "2026-03-10".
Recommended sequence:
  • Start with an explicit tool-call prompt such as Use the findtime MCP tool get_current_time for city "Tokyo" with countryCode "JP".
  • Once that works, switch to normal natural-language prompts such as Best meeting time between New York, Sydney, and Mumbai? or Does Cairo observe DST?
  • Cursor: the Output pane should show a successful stdio connection and the chat should call a findtime MCP tool.
  • Codex and Claude: the chat should call the MCP tool directly and should not fall back to repo search or local Node execution.
MCP

Troubleshooting

Use this section to diagnose startup failures, missing tools, auth errors, and false-positive fallback behavior.

Common setup issues:
  • Editing the wrong config file. Each client has its own MCP config source.
  • Leaving an old MCP server path in the config after moving the implementation to a new repo location.
  • Forgetting to provide a developer API key in the MCP client env.
  • Counting a local fallback execution as proof that MCP was working.
  • Restarting only the thread instead of the full client after changing MCP config.
SymptomLikely causeWhat to do
Startup timeout in CursorStale config, first-run install issue, or the wrong commandOpen Output, verify the command is npx -y @findtime/mcp-server, then reload Cursor after fixing the config.
initialize response failure in CodexOutdated MCP transport behavior or stale app processUpdate to the latest server code and fully quit and relaunch Codex.
Tool call returns 401Missing or wrong API keySet FINDTIME_TIME_API_KEY to a live developer key.
The model searched the repo and ran local JSMCP was still unavailableTreat that as fallback behavior, not success. Fix MCP first, then retry with a fresh thread.
Behavior seems stale even though MCP is connectedThe client may still be running an older MCP package, or the latest version lookup may have failedRun get_api_diagnostics. Check mcpInstallMode first, then compare mcpVersion and mcpLatestVersion. If the latest check fails, follow the returned npm or Official MCP Registry links to verify the newest published version manually.
Expected Cursor success logs
2026-03-21 14:33:22.064 [info] Starting new stdio process with command: npx -y @findtime/mcp-server
2026-03-21 14:33:22.123 [info] Successfully connected to stdio server
2026-03-21 14:33:22.123 [info] Storing stdio client: user-findtime
2026-03-21 14:33:22.123 [info] [MCP Allowlist] Creating adapter with serverName="findtime", identifier="user-findtime"
2026-03-21 14:33:22.123 [info] CreateClient completed, server stored: true
Cursor gotchas:
  • Editing the wrong file is the #1 trap. Verify whether Cursor is using the global config or a repo-local config.
  • If the Output pane shows a timeout during startup, check that the command is `npx -y @findtime/mcp-server` and that Cursor reloaded after the edit.
  • If the server connects but tool calls return 401, the missing piece is usually `FINDTIME_TIME_API_KEY`.
MCP

MCP tool surface

These tools are available through the findtime MCP server. Use them directly from your client once setup is complete.

ToolBest forWhy it matters
time_snapshotOne-call time intelligenceBest default tool when you want packaged location, timezone, current time, DST, and optional transitions. Batch calls can return per-location status with retry-friendly suggestedQuery and suggestedId values instead of failing all at once.
get_current_timeSingle-location time lookupsFastest current-time check when you already know the city or timezone you want. Exact country-name queries resolve directly for single-zone countries and return explicit ambiguity for multi-zone countries.
get_api_diagnosticsVersion and environment debuggingConfirms the running MCP version, reports whether the client is using a repo checkout or npm package install, checks the latest published MCP version when available, and returns the active API base URL, auth state, and health result.
get_dst_scheduleDST truthUse this when the question is specifically about DST status, last transition, next transition, or a calendar-year view like “When do clocks change in London this year?”
convert_timeOne-to-many conversionConvert a source local time into one or more target locations on a specific date.
get_overlap_hoursScheduling workflowsReturns shared overlap across locations instead of leaving the caller to compute it manually.
find_meeting_timeAgent and meeting planningReturns ranked meeting suggestions and a planner link back into findtime.io.
search_timezonesAmbiguity handlingResolve places like Victoria or timezone abbreviations like IST before a later tool call. countryCode is a ranking hint, not a strict result filter.
get_location_by_idDeterministic hydrationHydrate a stable `findtime:` location id when you want exact repeatability across calls.
v3.27-27-g2065f71a6-3307-2065f71