
findtime.io MCP Server
io.github.hkchaoPublished by GitHub account hkchaov3.28.1Updated Nov 3, 2026
MCP server for time in cities around the world, time zones, DST, conversion, and meetings.
Overview
findtime.io MCP server for world clock time, time zones, DST, time conversion and finding meeting times across cities.
- What you can do
- Answer natural-language time questions and get help or diagnostics
- Get current time, DST schedules, time zone search and location lookup
- Convert times and compute overlap hours between cities
- Find meeting times, check a proposed time, see who is awake, and rank recurring slots
- On the hosted server only: save, list, rename and delete saved teams
- On the hosted server only: request, reschedule, approve, decline and cancel bookings, and manage booking pages and invite links
- When to use it
- Useful when an assistant has to reason about time zones, daylight saving changes or ambiguous abbreviations, or when scheduling meetings across several cities. The hosted server adds saved groups and booking workflows for hosts who sign in with Google.
- Requirements
- Either the remote endpoint with OAuth sign-in, or the npm package run with npx on Node 20 or later. The npm package requires a findtime.io developer API key in FINDTIME_TIME_API_KEY and network access to the Time API. Booking and saved-team tools exist only on the hosted server and need a Google sign-in with a verified email.
Installation
In SourceWeft
- Open findtime.io MCP Server in the dashboard and add it to a workspace.
- Connect the required credentials. They are stored privately and never shown on public pages.
- Enable the server for the chats that should use its tools.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Use with an agent
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.hkchao%2Ffindtime-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Other MCP clients
Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.
{
"mcpServers": {
"findtime-io": {
"type": "http",
"url": "https://mcp.findtime.io/mcp"
}
}
}README
@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 - Hosted server:
https://mcp.findtime.io/mcp(Streamable HTTP, OAuth sign-in). It includes the time tools and saved teams. Booking tools (request, reschedule and cancel bookings; host approve/decline; booking pages and invite links) are available after you sign in with Google through the connector and grant the booking scopes. See Hosted server scopes for which OAuth scope covers which tool. The npm package covers the time and meeting-planning tools only and needsFINDTIME_TIME_API_KEY. It has no saved-group or booking tools: those need a findtime account signed in with Google on the hosted server, and an API key never gets booking tools.
Hosted server scopes
The hosted server's OAuth metadata (/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server) lists only the two default scopes, time:read and meetings:plan. A client that connects without naming a scope gets both. The booking scopes, booking:request and booking:host, are left out of scopes_supported on purpose, so a client that copies that list on first connect never asks for host access. They are still granted when a client asks for them by name.
When a signed-in client calls a booking tool without the scope it needs, the server answers 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="...". The scope value is the full set to ask for on the next sign-in. Asking for booking:host shows a findtime consent screen before Google sign-in.
The findtime booking API checks booking:request and booking:host again on its side, using a signed assertion from the hosted server. Those tools also need the person signed in to findtime with Google and a verified email. Finding a host's open times needs no booking scope. A Time API key (ftk_live_...) used as a bearer token gets time:read meetings:plan only and never sees the booking tools.
Tool surface
The npm package (stdio, API key) and the hosted server both have:
answer_time_questionget_findtime_helpget_api_diagnosticssend_feedback(reports a wrong answer; sends the tool name, never the query text)time_snapshotget_current_timeget_dst_scheduleconvert_timeget_overlap_hoursfind_meeting_timecheck_proposed_time(/meeting/check: verdicts for a time the user already picked)are_they_awake(/meeting/awake: work, awake, or sleep in other cities at one moment)rank_recurring_slot(/meeting/recurring: who a weekly time punishes, plus a kinder slot)search_timezonesget_location_by_id
Hosted server only (https://mcp.findtime.io/mcp, signed in with Google). These are not in the npm package and never will be on an API key:
- Saved groups:
save_team,get_team,list_teams,rename_team,delete_team. They read and write the homepage planner Saved groups of the signed-in Google account. On the npm package, ateamIdwithout locations answersteams_not_persisted; pass locations on each call. - Booking:
get_host_booking_profile,find_host_slots,request_booking,get_booking_status,list_my_booking_requests,cancel_booking,reschedule_booking,get_my_booking_page,list_booking_requests,approve_booking_request,decline_booking_request,cancel_booking_as_host,update_booking_page,create_invite_link,revoke_invite_link. Every booking write returns a read-back first and changes nothing until it is called again withconfirm: true; the host approves or declines every request.
Scopes for each hosted tool are in Hosted server scopes. Tool and setup docs: https://findtime.io/developers/mcp/#booking-tools. The booking routes these tools call: https://findtime.io/developers/#booking-api.
Prefer answer_time_question 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:
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+
FINDTIME_TIME_API_KEY: a validfindtime.iodeveloper key fromhttps://findtime.io/developers/keys/
Optional environment variables:
FINDTIME_TIME_API_BASE_URLTIME_API_BASE_URLTIME_API_TIMEOUT_MSFINDTIME_BINDING_TYPEfor optional install/workspace binding context. Supported values:slack_team,workspace_id,install_id.FINDTIME_BINDING_VALUEfor the install/workspace identifier that matches the selected binding type.FINDTIME_BINDING_HEADERto override the header name directly for custom enterprise environments.FINDTIME_MCP_CLIENT_IDorFINDTIME_MCP_INSTALL_IDto 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 totime-apiasX-Findtime-User-IDfor enterprise usage attribution.FINDTIME_MCP_CLIENT_TYPEFINDTIME_MCP_TOOL_MODE=answer-onlyto expose onlyanswer_time_question,get_findtime_help, andget_api_diagnosticsfor enterprise bots that should route every natural-language request through the answer API.FINDTIME_MCP_INSTRUMENTATION_ENABLED=falseto opt out of anonymous usage telemetry.FINDTIME_MCP_USAGE_TELEMETRY_URLto 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.
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 FINDTIME_MCP_CLIENT_ID or FINDTIME_MCP_INSTALL_ID behavior.
Privacy contract: _endUserId must be an opaque token supplied by the MCP host, typically a SHA-256 hash of the platform user ID truncated to 16-32 hex characters. Do not send raw email addresses, names, Slack/Discord/Teams IDs, or other PII. Avoiding PII in this field is the host application's responsibility.
The server validates _endUserId defensively: it must be a string, at most 256 characters, and must not contain CR, LF, or other control characters. The raw value is never logged by the server.
Cursor Marketplace plugin
This repository also packages the hosted findtime.io connector as a Cursor plugin. The manifest lives in .cursor-plugin/plugin.json, and mcp.json connects to https://mcp.findtime.io/mcp.
After installing the plugin in Cursor, enable its MCP server and complete Google OAuth when prompted. The hosted service supports time queries, meeting planning, saved location groups, and booking tools. Preview booking changes and confirm the returned details before sending or cancelling a request. Hosts approve or decline requests separately.
For manual hosted setup, add the following to your Cursor MCP configuration.
The API-key instructions below apply to the local npm server. Hosted setup and permissions are documented at https://findtime.io/developers/mcp/.
Cursor stdio configuration
Codex
Claude Desktop
Claude CLI / Claude Code
Add findtime.io with:
If your Claude CLI uses JSON config instead, add:
For enterprise installs, the minimum credential is always the API key. If the install environment has a stable workspace or installation identifier, optionally add:
For Slack-specific installs:
Verify installation
Use an explicit tool-call prompt first:
Then:
After that succeeds, switch back to normal natural-language prompts:
Local development
Run the workspace version directly:
The server attempts to load .env.development.local, .env.development, .env.local, and .env from:
- the current working directory
services/mcp-server- the repo root
Tests
Protocol and transport tests:
Live production-parity smoke tests:
The smoke suite checks:
search_timezonesanswer_time_questionget_current_timeget_dst_scheduleconvert_timeget_overlap_hoursfind_meeting_timeget_location_by_id
Maintainer release flow
The canonical public source for this package now lives in:
- GitHub:
https://github.com/hkchao/findtime-mcp-server - npm:
@findtime/mcp-server - Official MCP Registry:
https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server
Publish and version updates should happen from that public repo, not from this private app repo.
Releases publish from CI when a v<version> tag is pushed: .github/workflows/publish.yml publishes to npm with trusted publishing (GitHub OIDC), then calls .github/workflows/publish-mcp-registry.yml to publish server.json to the MCP Registry. The full runbook (manual dispatch, re-runs, error fixes, and the hand-publish fallback) is the "Maintainer Release Playbook" in SKILL.md.
Standard release flow in the public repo, after bumping package.json and server.json and merging to main:
Hand publishing is a fallback only. prepublishOnly rejects it unless you set the acknowledgement that release:check prints:
The equivalent local verification checks in this repo are:
Treat this repo as the implementation source that originally produced the MCP package, not as the canonical public release source.
Publisher and tool safety
The npm package @findtime/mcp-server and GitHub repository
hkchao/findtime-mcp-server are the findtime.io MCP distribution channels.
Product documentation: https://findtime.io/developers/mcp/
The npm package's tools query time information, suggest meeting times, or
return help and diagnostics; they do not book meetings or modify calendars.
They declare readOnlyHint: true, destructiveHint: false,
idempotentHint: true, and openWorldHint: true, except send_feedback, which
records a report and declares readOnlyHint: false, destructiveHint: false,
and idempotentHint: false. Read-only describes the user-facing operation, not
an absence of network traffic: API requests, diagnostics, and optional usage
telemetry contact external services. Repeating a current-time query can return a
new time; idempotent describes the absence of additional domain mutations.
The hosted server at https://mcp.findtime.io/mcp also has booking tools that
do write: requesting, rescheduling, approving, declining, and cancelling
bookings, changing a booking page, and making or revoking invite links.
Approving or cancelling a meeting changes the host's Google Calendar. Those
tools declare readOnlyHint: false, and the ones that cancel, decline, or
revoke declare destructiveHint: true. They are not part of this package.
API-key environment variables are alternative configuration names for one key, not four separate credentials.
Privacy, authentication, and service limits
Privacy policy: https://findtime.io/privacy/
The stdio process runs locally. Time tools send their query arguments to the
configured Time API (by default https://time-api.findtime.io). The selected API
key is sent in the Authorization: Bearer header to that API, not to npm or
telemetry. Configure only API hosts you trust. The four API-key variable names
are aliases: the first nonempty value wins in this order: FINDTIME_API_KEY,
TIME_API_KEY, FINDTIME_MCP_API_KEY, FINDTIME_TIME_API_KEY.
The hosted Time API owns API-key validation, configured per-key rate limits, and quotas. The wrapper forwards upstream failures, including HTTP 429, as MCP tool errors. It does not expose a public HTTP listener or implement a separate local rate limiter. Help is local; diagnostics also reads npm version metadata.
send_feedback posts only the tool name to /mcp/feedback on the configured
Time API. It never sends the query text or whatWasWrong. The result reports
the server's answer: 202 means recorded, 204 means findtime.io received the
report but did not keep it (not an error, nothing to retry), and any other
2xx means accepted. Other statuses are error results.
Optional usage telemetry goes to https://slack.findtime.io/telemetry/usage by
default. The wrapper sends tool name, outcome, query-text length, a persistent
installation/client identifier, version, OS, locale, timezone, and latency.
This telemetry event does not include raw query text, API keys, or the per-call
_endUserId. Set FINDTIME_MCP_INSTRUMENTATION_ENABLED=false to disable it.
A generated installation identifier is stored in the user's state directory.
Host-provided attribution identifiers are sent to the Time API as documented
above; use opaque non-PII values.
License
The MCP wrapper and documentation in this repository are licensed under the MIT License.
This license covers this repository only. It does not grant rights to the hosted findtime.io Time API, its backend implementation or data, or the broader findtime.io application. Use of hosted services remains subject to their applicable terms and API access requirements.
Source: README.md at commit 6f46ed7
Tools
0Version history
5- v3.28.1LatestNov 3, 2026
- v3.28.0Nov 1, 2026
- v3.27.3Sep 19, 2026
- v3.27.2Sep 17, 2026
- v3.25.15Sep 16, 2026
Score
85% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 daysRequired25 pts
- Auth declaredRequired10 pts
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts