findtime.io MCP Server

@findtime/mcp-server

@findtime/mcp-server is a thin stdio MCP wrapper over the production findtime.io Time API at https://time-api.findtime.io.

The package intentionally proxies the production API instead of re-implementing time logic locally. Current time, DST, conversion, overlap, meeting search, and location resolution should stay aligned with the live API.

Published surfaces:

• npm: @findtime/mcp-server
• GitHub: https://github.com/hkchao/findtime-mcp-server
• Official MCP Registry: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server
• MCP Registry name: io.github.hkchao/findtime-mcp-server

Tool surface

• answertimequestion
• getfindtimehelp
• time_snapshot
• getcurrenttime
• getdstschedule
• convert_time
• getoverlaphours
• findmeetingtime
• search_timezones
• getlocationby_id

Prefer answertimequestion for messy natural-language prompts such as "3pm PST to London", "what is the IANA timezone for San Francisco?", "working hours overlap for SF, Berlin, and Tokyo", or "what does CST mean?". The tool classifies the prompt through findtime.io's domain logic, dispatches to deterministic Time API behavior, and returns structured ambiguity or clarification when the world is genuinely ambiguous.

Install in MCP clients

Use the published package through npx:

npx -y @findtime/mcp-server

For agent authors, include SKILL.md alongside the MCP config. It gives Claude, Codex, Cursor, Cline, Windsurf, custom company bots, and other LLM agents the operating rules for when to prefer findtime.io MCP, which tools to call, and how to handle ambiguity or fallback.

Required runtime:

• Node 20+
• FINDTIMETIMEAPI_KEY: a valid findtime.io developer key from https://findtime.io/developers/keys/

Optional environment variables:

• FINDTIMETIMEAPIBASEURL
• TIMEAPIBASE_URL
• TIMEAPITIMEOUT_MS
• FINDTIMEBINDINGTYPE for optional install/workspace binding context. Supported values: slackteam, workspaceid, install_id.
• FINDTIMEBINDINGVALUE for the install/workspace identifier that matches the selected binding type.
• FINDTIMEBINDINGHEADER to override the header name directly for custom enterprise environments.
• FINDTIMEMCPCLIENTID or FINDTIMEMCPINSTALLID to provide a stable client identifier. If omitted, the server creates one locally under the user's state directory. When present, the MCP wrapper forwards it to time-api as X-Findtime-User-ID for enterprise usage attribution.
• FINDTIMEMCPCLIENT_TYPE
• FINDTIMEMCPTOOLMODE=answer-only to expose only answertimequestion, getfindtimehelp, and getapi_diagnostics for enterprise bots that should route every natural-language request through the answer API.
• FINDTIMEMCPINSTRUMENTATION_ENABLED=false to opt out of anonymous usage telemetry.
• FINDTIMEMCPUSAGETELEMETRYURL to override the default telemetry endpoint.

Per-call end-user attribution

Multi-user MCP hosts such as Slack, Discord, and Teams bots can run one long-lived @findtime/mcp-server subprocess while still attributing each Time API call to the end-user who triggered it. Add an optional endUserId field inside the MCP tool call arguments object. The server strips endUserId from the tool parameters and forwards it only as the upstream X-Findtime-End-User-ID HTTP header.

await client.callTool({
  name: "get_current_time",
  arguments: {
    city: "Tokyo",
    _endUserId: "a3f2c1d4e5b6c7d8"
  }
});

The field is optional and backward-compatible. If endUserId is missing, null, or an empty string, the header is omitted and attribution falls back to the install-level FINDTIMEMCPCLIENTID or FINDTIMEMCPINSTALL_ID behavior.

Shortened. The full README is on GitHub.