Skip to main content
Glama

@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

  • answer_time_question

  • get_findtime_help

  • time_snapshot

  • get_current_time

  • get_dst_schedule

  • convert_time

  • get_overlap_hours

  • find_meeting_time

  • search_timezones

  • get_location_by_id

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.

Related MCP server: Time MCP Server

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+

  • FINDTIME_TIME_API_KEY: a valid findtime.io developer key from https://findtime.io/developers/keys/

Optional environment variables:

  • FINDTIME_TIME_API_BASE_URL

  • TIME_API_BASE_URL

  • TIME_API_TIMEOUT_MS

  • FINDTIME_BINDING_TYPE for optional install/workspace binding context. Supported values: slack_team, workspace_id, install_id.

  • FINDTIME_BINDING_VALUE for the install/workspace identifier that matches the selected binding type.

  • FINDTIME_BINDING_HEADER to override the header name directly for custom enterprise environments.

  • FINDTIME_MCP_CLIENT_ID or FINDTIME_MCP_INSTALL_ID 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.

  • FINDTIME_MCP_CLIENT_TYPE

  • FINDTIME_MCP_TOOL_MODE=answer-only to expose only answer_time_question, get_findtime_help, and get_api_diagnostics for enterprise bots that should route every natural-language request through the answer API.

  • FINDTIME_MCP_INSTRUMENTATION_ENABLED=false to opt out of anonymous usage telemetry.

  • FINDTIME_MCP_USAGE_TELEMETRY_URL 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 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

{
  "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"
      }
    }
  }
}

Codex

[mcp_servers.findtime]
command = "npx"
args = ["-y", "@findtime/mcp-server"]
enabled = true

[mcp_servers.findtime.env]
FINDTIME_MCP_CLIENT_TYPE = "codex"
FINDTIME_TIME_API_BASE_URL = "https://time-api.findtime.io"
FINDTIME_TIME_API_KEY = "YOUR_FINDTIME_SECRET_KEY"
# Optional enterprise install binding:
# FINDTIME_BINDING_TYPE = "workspace_id"
# FINDTIME_BINDING_VALUE = "YOUR_WORKSPACE_ID"

Claude Desktop

{
  "preferences": {
    "...": "keep your existing preferences here"
  },
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
        "env": {
          "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
          "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
        }
      }
    }
  }

Claude CLI / Claude Code

Add findtime.io with:

claude mcp add --transport stdio \
  --env FINDTIME_TIME_API_BASE_URL=https://time-api.findtime.io \
  --env FINDTIME_TIME_API_KEY=YOUR_FINDTIME_SECRET_KEY \
  --env FINDTIME_MCP_CLIENT_TYPE=claude-cli \
  findtime -- npx -y @findtime/mcp-server

If your Claude CLI uses JSON config instead, add:

{
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY",
        "FINDTIME_MCP_CLIENT_TYPE": "claude-cli"
      }
    }
  }
}

For enterprise installs, the minimum credential is always the API key. If the install environment has a stable workspace or installation identifier, optionally add:

FINDTIME_BINDING_TYPE=workspace_id
FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID

For Slack-specific installs:

FINDTIME_BINDING_TYPE=slack_team
FINDTIME_BINDING_VALUE=T01ABC123

Verify installation

Use an explicit tool-call prompt first:

Use the findtime.io MCP tool get_api_diagnostics.

Then:

Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".

After that succeeds, switch back to normal natural-language prompts:

Best meeting time between New York, Sydney, and Mumbai?

Local development

Run the workspace version directly:

npm run mcp:start

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:

npm run test:mcp-server

Live production-parity smoke tests:

npm run test:mcp-server:smoke

The smoke suite checks:

  • search_timezones

  • answer_time_question

  • get_current_time

  • get_dst_schedule

  • convert_time

  • get_overlap_hours

  • find_meeting_time

  • get_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.

Standard publish flow in the public repo:

npm test
npm pack --dry-run
npm publish --access public

The equivalent local verification checks in this repo are:

npm run test:mcp-server
npm run mcp:pack

Treat this repo as the implementation source that originally produced the MCP package, not as the canonical public release source.

Available Tools

11 tools
answer_time_questionA

PREFERRED entry point for time/timezone/scheduling questions. findtime.io classifies intent and dispatches internally. Use this WHENEVER the user's input includes a natural-language day or date qualifier, such as "Tuesday", "next Friday", "tomorrow", "tonight", "this weekend", "in 3 weeks", or "last Monday". The specific tools (convert_time, get_current_time, find_meeting_time, etc.) will silently drop these qualifiers if you dispatch to them without an explicit ISO date. Also the right choice for vague or mixed-intent prompts.

ParametersJSON Schema
NameRequiredDescriptionDefault
nowNoOptional ISO timestamp for deterministic relative-date handling.
dateNoOptional YYYY-MM-DD date context.
queryYesThe raw user time-related question or prompt.
localeNoOptional user locale hint, such as en-US.
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
userTimezoneNoOptional IANA timezone for the user, used for relative questions like "my time" or "tomorrow".

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It communicates that the tool classifies intent and dispatches internally, warns that other tools silently drop natural-language qualifiers without an explicit ISO date, and notes suitability for vague/mixed intent. It does not mention auth, rate limits, or return format, but the core behavior is clearly surfaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three focused sentences, with the most important information front-loaded. The contrast with alternatives and the natural-language examples earn their place with no redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic intent-router with no output schema, the description covers the core selection behavior, when to use it, why it is preferred, and how to distinguish it from sibling tools. It does not state the return shape, but the name and entry-point nature make the intended answer clear. Overall, it is adequately complete for safe and accurate selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds useful context around what the 'query' parameter should contain (natural-language time questions), but does not elaborate on parameters like 'now', 'date', or 'locale' beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific purpose: it is the 'PREFERRED entry point for time/timezone/scheduling questions' and explains that it classifies intent and dispatches internally. This clearly distinguishes it from the sibling tools that operate on already-structured time data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance: use it WHENEVER there is a natural-language day/date qualifier, and provides concrete examples like 'Tuesday' and 'next Friday'. It also warns against alternatives that 'silently drop' these qualifiers and recommends it for 'vague or mixed-intent prompts'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_timeA

Convert a source local time into one or more target locations using the production conversion endpoint. Use ONLY when date is an explicit ISO calendar date (YYYY-MM-DD) you can pass in, OR the conversion is for the current moment with no date qualifier at all. DO NOT use this tool if the user said "Tuesday", "tomorrow", "next Friday", or any other relative day/date phrase; those qualifiers will be silently dropped here. Route to answer_time_question instead, which parses relative dates correctly. When presenting results, copy localTime.weekday, localTime.date, localTime.time12h/time24h, timezone abbreviation, and UTC offset exactly from the tool output; do not recompute or shift day names during synthesis.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYes
dateNoOptional ISO date used as the conversion context.
fromYesSource location or timezone.
timeYesSource local time, such as "9:00 AM".
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
toCountryCodesNo
fromCountryCodeNoOptional ISO country hint for the source location.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses a critical behavioral quirk—relative date qualifiers are 'silently dropped'—and instructs downstream synthesis to copy localTime fields and offsets exactly, revealing part of the output contract. It does not discuss failure modes or error behavior, but the key behavioral risk for this conversion tool is clearly addressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, then gives crisp usage constraints, a named alternative, and output-handling rules. Every sentence earns its place with no redundancy; the length is justified by the routing and synthesis instructions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with no output schema or annotations, the description covers purpose, valid usage conditions, a sibling alternative, and the key output fields to preserve. It could additionally describe error behavior or the country-hint parameters, but the essential decision-making context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71%, and the description adds meaningful value by constraining date to explicit ISO calendar dates and clarifying that current-moment conversions require no date qualifier. It also reinforces the meaning of from/time/to beyond what the raw property names convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and object: 'Convert a source local time into one or more target locations.' It clearly distinguishes itself from siblings by explicitly routing relative-date questions to answer_time_question, making the tool's scope concrete and non-overlapping.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit use conditions: use only with explicit ISO calendar dates or current-moment conversions, and explicitly says 'DO NOT use' for relative phrases like 'tomorrow' or 'next Friday.' It names answer_time_question as the alternative, fully satisfying when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_meeting_timeA

Return ranked meeting suggestions from the production meeting search endpoint. For relative-date inputs ("this week", "next Friday", "tomorrow"), route to answer_time_question, which resolves the relative date and dispatches internally.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoOptional ISO date to anchor the meeting search.
locationsYes
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
countryCodesNo

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'production meeting search endpoint', which implies a live query but does not explicitly state read-only behavior, side effects, authentication requirements, or other operational traits. It also does not disclose potential failure modes or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, immediately stating the purpose and then giving a critical routing rule. It is front-loaded with the main action and wastes no words, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain the return format. It only says 'ranked meeting suggestions', which is vague and does not specify the structure, ranking criteria, or pagination. There is no mention of error handling or edge cases, and with no annotations the agent gets little guidance for production use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%, so the description should compensate for the remaining parameters. It adds minimal value: it only hints that 'date' should be absolute by routing relative dates elsewhere, but does not explain semantics for locations, countryCodes, or _endUserId beyond what the schema already states. The description does not clarify constraints, formats, or relationships between parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns ranked meeting suggestions from a specific endpoint, using a specific verb ('return') and resource ('production meeting search endpoint'). It also distinguishes itself from the sibling tool answer_time_question by explicitly mentioning the routing condition for relative-date inputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: for relative-date inputs ('this week', 'next Friday', 'tomorrow'), it instructs routing to answer_time_question. This is a clear when-not-to-use condition, and the mention of 'production search endpoint' implicitly defines its intended use for absolute dates. The alternative tool is named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_api_diagnosticsA

Return MCP and findtime Time API diagnostics, including the running MCP version, latest published MCP version, API base URL, auth configuration, and a live health check.

ParametersJSON Schema
NameRequiredDescriptionDefault
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the tool returns diagnostic info and includes a live health check, implying network activity arenas but does not mention potential side effects, failure modes, or permission requirements. Adds reasonable context but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the purpose ('Return MCP and findtime Time API diagnostics') and efficiently lists the returned components. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has low complexity (1 optional param, no output schema), and the description covers the main functionality. It could mention that the health check may incur network latency or that the auth configuration might be sensitive, but it's adequate for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully explains the single optional parameter. The tool description does not mention the parameter, but the baseline of 3 applies since schema handles parameter semantics adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns diagnostics for the MCP and findtime API, listing specific items like version, URL, auth config, and health check. It is easily distinguished from sibling tools, which all focus on time-related operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The tool's purpose is unique among siblings, so usage context is clear from the description (diagnostics). However, it does not explicitly state when to use it versus alternatives or any exclusions, though none seem necessary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_current_timeA

Return the production current time payload for a single city, query, or timezone. Exact country-name queries may be retried through a canonical city when the resolver can do so deterministically. For relative-date inputs ("Tuesday", "next Friday", "tomorrow", "tonight"), route to answer_time_question, which resolves the relative date and dispatches internally.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityNoCity name such as "Tokyo".
queryNoFree-form location query, country name, or timezone abbreviation.
timezoneNoDirect IANA timezone, such as "Europe/London".
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
countryCodeNoOptional ISO country hint for ambiguous city names.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden. It explains the retry behavior for country-name queries, which is useful. However, it does not disclose other behavioral aspects such as error handling, rate limits, or the structure of the payload, but given the tool's simplicity, the description provides sufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place. The first sentence states the core purpose, the second provides a nuanced behavior, and the third gives an explicit routing rule. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters, 0 required, no output schema, and no annotations. The description covers the core use cases and provides a crucial exclusion for relative dates, but does not fully compensate for lack of output structure or edge-case handling. However, the description is adequate for the tool's simplicity and the schema's completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal param-specific meaning (e.g., mentions city, query, timezone in the purpose). It does not elaborate on mutual exclusivity or priorities among the fields, but the schema's coverage is high, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the current time payload for a city, query, or timezone, and distinguishes it from the sibling tool answer_time_question by specifying that relative-date inputs should not be handled here. The verb 'Return' plus the resource 'production current time payload' is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to route relative-date inputs to answer_time_question, providing a clear when-not-to-use directive and naming the alternative. It also mentions that exact country-name queries may be retried through a canonical city, giving concrete usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dst_scheduleA

Return the production DST schedule payload, including current abbreviation and transition details. For relative-date inputs ("this week", "next Friday", "tomorrow"), route to answer_time_question, which resolves the relative date and dispatches internally.

ParametersJSON Schema
NameRequiredDescriptionDefault
atNoOptional ISO timestamp used as the reference instant.
cityNoCity name such as "Reykjavik".
yearNoOptional calendar year used to return DST transitions for that civil year.
queryNoFree-form location query.
timezoneNoDirect IANA timezone, such as "America/New_York".
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
countryCodeNoOptional ISO country hint for ambiguous city names.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of explaining behavior. It discloses what the tool returns and something about its content, but it does not mention default behavior when no optional parameters are provided, handling of ambiguous locations, or error/fallback behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and the second sentence provides an actionable routing rule. Every sentence earns its place without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 optional parameters and no output schema, the description gives a broad purpose but does not explain how arguments (year, at, timezone/city/query, countryCode) interact or what happens for missing inputs. It is minimally sufficient but leaves important edge cases uncovered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents every parameter. The description adds no parameter-specific meaning, but because coverage is complete and the baseline is 3, this is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and a clear resource ('production DST schedule payload'), and specifies key contents ('current abbreviation and transition details'). It also distinguishes itself from the sibling answer_time_question by explicitly routing relative-date queries there.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states that relative-date inputs should go to answer_time_question instead of this tool, which is a useful when-not-to-use condition. It does not elaborate on other alternatives like time_snapshot or search_timezones, but it gives enough context for the primary routing decision.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_findtime_helpB

Return enterprise-friendly findtime.io MCP usage help, including supported time-intelligence intents, answer API examples, ambiguity handling examples, and recommended answer-only deployment guidance.

ParametersJSON Schema
NameRequiredDescriptionDefault
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It reveals that the tool returns documentation/help content, not operational data, which is useful. However, it doesn't state whether it performs network calls, caches, or has any side effects, but for a help tool this is acceptable. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that lists the key content areas, which is concise and front-loaded. It's not overly verbose, but could be slightly more structured (e.g., bullets), but as a paragraph it's acceptable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one optional parameter and no output schema, so the description suffices to convey its purpose and content. It could be improved by adding a note about the output format (e.g., plain text vs JSON), but given low complexity, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not mention the single parameter '_endUserId'. However, schema coverage is 100%: the schema already explains that it's an optional end-user attribution token and warns against sending PII. Thus, the description adds no extra value here, and a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns usage help for findtime.io MCP, listing several specific content types (time-intelligence intents, answer API examples, ambiguity handling, deployment guidance). This is distinct from sibling tools that perform time operations like answering questions or finding meeting times, though it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for learning how to use the MCP, but it doesn't explicitly state when to use it versus alternatives. Given siblings like answer_time_question and find_meeting_time, a user might need this help before using those, but the description doesn't say that directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_location_by_idA

Hydrate an exact production location record by stable findtime id.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesStable location id such as "findtime:victoria|CA|America/Vancouver".
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. 'Hydrate' implies a read-only, idempotent fetch of a full record, and 'production' signals real vs. test data — useful context. But failure modes for unknown/missing IDs, response shape, and absence of side effects are left unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 11-word sentence front-loads the verb and packs in matching precision ('exact'), data environment ('production'), and keying mechanism ('stable findtime id'). Every word earns its place with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-required-param lookup with 100% schema coverage, the description is nearly sufficient. The notable gap is that with no output schema, it does not state what a 'location record' contains (e.g., offset, DST info, aliases) or error behavior for unknown IDs — moderate gaps for an agent deciding whether this tool answers a time question.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: the id parameter includes a concrete format example ('findtime:victoria|CA|America/Vancouver') and _endUserId has a thorough privacy- and provenance-oriented description. The tool description adds only 'stable findtime id,' which reinforces but does not exceed the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Hydrate'), resource ('exact production location record'), and method ('by stable findtime id'), clearly stating an exact-ID lookup rather than a search. This distinguishes it from the closest sibling, search_timezones, which finds locations without a stable ID.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'by stable findtime id' phrase implies the caller must already possess a findtime ID, so context is inferable. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named (e.g., 'use search_timezones to find an ID first').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_overlap_hoursA

Return shared business-hours overlap across multiple locations using the production overlap endpoint. For relative-date inputs ("this week", "next Friday", "tomorrow"), route to answer_time_question, which resolves the relative date and dispatches internally.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoOptional ISO date used to compute overlap.
locationsYes
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
countryCodesNo

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool uses a 'production overlap endpoint' (implying a network call) and that relative dates are not handled directly (delegated to answer_time_question). However, it does not explicitly state read-only nature, error behavior, or any side effects, leaving some behavioral aspects undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences. The first sentence front-loads the primary purpose, and the second provides essential routing guidance. Every word earns its place, with no filler or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should explain what the tool returns, but it does not mention the output format, error cases, or how countryCodes/date affect the result. The routing rule adds some context, but the lack of return-value specification is a significant gap for a tool that computes overlap hours.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%, and all parameters have descriptions in the schema (date, locations, _endUserId, countryCodes). The description adds no extra meaning to the parameters themselves, only the date-related routing rule. Since coverage is moderate, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Return shared business-hours overlap across multiple locations' with a specific verb and resource. It also distinguishes from the sibling tool answer_time_question by explicitly noting that relative-date inputs should be routed elsewhere, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-not-to-use guidance: 'For relative-date inputs... route to answer_time_question.' This names the alternative tool and the condition for using it, which is exactly the kind of guidance needed for correct tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_timezonesB

Search production location records by city, country, or timezone-related query.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return.
queryYesSearch term such as "Victoria", "Sao Paulo", or "Tokyo".
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
countryCodeNoOptional ISO country hint used for ranking and disambiguation. This is not a strict filter.

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only says 'search' and does not disclose whether the operation is read-only, how countryCode affects ranking/disambiguation, return format, or behavior like limit enforcement. These gaps are significant for a tool with no annotation safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Every phrase adds meaning, and it is appropriately sized for a straightforward search tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with full schema coverage, the core purpose is communicated. However, with no annotations and no output schema, the description leaves unspecified return shape, result limits, and ordering — gaps that keep it from being fully complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents query, limit, countryCode, and _endUserId. The description adds only that searches can be by 'city, country, or timezone-related query,' which aligns with query but adds no syntax or behavior detail beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and identifies the resource ('production location records') with clear query dimensions (city, country, timezone). It distinguishes itself from sibling tools like get_current_time or convert_time, though it does not explicitly name alternatives, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: use this tool when you need to find location records via a text query. However, it does not explicitly state when not to use it or name alternatives such as get_location_by_id for exact ID lookups, making the guidance only implicitly clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

time_snapshotC

Return the production time snapshot payload for one location or a list of locations.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoSingle location query such as "Tokyo" or "Europe/London".
locationsNo
_endUserIdNoOptional opaque per-call end-user attribution token populated by the MCP host, not the LLM. Use a non-PII hash or token; never send raw email, name, or platform user ID.
countryCodeNoOptional ISO country hint for a single query.
countryCodesNo
includeTransitionsNoInclude last and next timezone transition details.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full transparency burden. It does not disclose what the snapshot payload contains, how query and locations interact, or any edge cases or limitations. Only the basic return action and scope are stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, and the primary operation is front-loaded. It is as concise as possible, though the brevity trades away contextual depth.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With six parameters, no output schema, and no annotations, the description is too thin: it never explains the payload shape, the relationship between query and locations, or the intended use case. An agent may struggle to select this tool over get_current_time or combine parameters correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Most parameter meaning is provided by the input schema, which documents query, locations, country code hints, and includeTransitions. The description only restates the one/location list dimension and adds little beyond what the schema already covers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a clear action ('Return'), a specific resource ('production time snapshot payload'), and a scope ('one location or a list of locations'). It is distinct enough from siblings like get_current_time, though it does not explicitly name an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus get_current_time, get_dst_schedule, convert_time, or search_timezones. The phrase 'snapshot payload' implies raw data retrieval, but there are no explicit usage conditions, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 11 tool updatesv3.27.0
    • First observedanswer_time_question
    • First observedconvert_time
    • First observedfind_meeting_time
    • First observedget_api_diagnostics
    • First observedget_current_time
    • First observedget_dst_schedule
    • First observedget_findtime_help
    • First observedget_location_by_id
    • First observedget_overlap_hours
    • First observedsearch_timezones
    • First observedtime_snapshot

TDQS

A3.6/5.0

Scored across 11 tools

Disambiguation4/5

Tools are well-differentiated with clear instructions. The answer_time_question tool is explicitly designated for relative-date queries, while specific tools like convert_time, get_current_time, and find_meeting_time are for exact dates or current moment. Some potential confusion between time_snapshot and get_current_time, which both return time-related payloads, but descriptions help distinguish them.

Naming Consistency4/5

Most tools follow a verb_noun pattern (get_current_time, convert_time, search_timezones, etc.). One deviation is time_snapshot, which is noun_verb, and answer_time_question follows the pattern. Overall, the naming is consistent and readable, with only a minor deviation.

Tool Count4/5

11 tools is a reasonable number for a time-intelligence server. The set includes core operations (conversion, current time, overlap, meeting time), utility (search, location lookup), diagnostics, help, and an entry point. There is slight redundancy between time_snapshot and get_current_time, but the count is not excessive or insufficient.

Completeness4/5

The tool set covers the major time-related workflows: current time, conversion, DST schedule, overlap, meeting suggestions, and location resolution. It also includes diagnostics and help for enterprise deployment. It lacks some advanced features like timezone math or calendar integration, but for its stated purpose it appears comprehensive.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Gives large language models time awareness capabilities through various time-related functions including current time retrieval, timezone conversion, and relative time calculations.
    6
    1,160
    MIT
  • A
    license
    B
    quality
    D
    maintenance
    Provides time and timezone functionality for LLMs, enabling them to get current time information across different timezones and convert times between zones.
    2
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to get current time information for any timezone worldwide, including available regions, cities, and ISO 8601 formatted timestamps with timezone offsets.
    8
    -
  • A
    license
    B
    quality
    D
    maintenance
    Provides current time information and timezone conversion capabilities using IANA timezone names with automatic system detection. It enables LLMs to fetch local or global times and convert specific timestamps between different regions.
    2
    2
    MIT