Skip to main content
Glama
ampcome-mcps

Time MCP Server

by ampcome-mcps

🚀 Time MCP Server: Giving LLMs Time Awareness Capabilities

A Model Context Protocol (MCP) server implementation that allows LLMs to have time awareness capabilities.

Tools

  • current_time: Get current time (UTC and local time)

  • relative_time: Get relative time

  • get_timestamp: Get timestamp for the time

  • days_in_month: Get days in month

  • convert_time: Convert time between timezones

  • get_week_year: Get week and isoWeek of the year

Related MCP server: Time MCP Server

Installation

Installing via Smithery

To install time-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @yokingma/time-mcp --client claude

Manually install (Optional)

npm install -g time-mcp

using npx

npx -y time-mcp

Running on Cursor

Your mcp.json file will look like this:

{
  "mcpServers": {
    "time-mcp": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    }
  }
}

Running on Windsurf

Add this to your ./codeium/windsurf/model_config.json file:

{
  "mcpServers": {
    "time-mcp": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    }
  }
}

License

MIT License - see LICENSE file for details.

Available Tools

6 tools
convert_timeB

Convert time between timezones.

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceTimezoneYesThe source timezone. IANA timezone name, e.g. Asia/Shanghai
targetTimezoneYesThe target timezone. IANA timezone name, e.g. Europe/London
timeYesDate and time in 24-hour format. e.g. 2025-03-23 12:30:00

TDQS

B3.1/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 states the tool converts time but doesn't disclose behavioral traits such as error handling (e.g., invalid timezone inputs), format requirements beyond the schema, or whether it performs validation. This leaves gaps in understanding how the tool behaves in edge cases.

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, clear sentence with zero waste. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration, making it highly efficient.

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?

Given the tool's moderate complexity (time conversion with three parameters) and no annotations or output schema, the description is minimally adequate. It states what the tool does but lacks details on behavior, usage context, or output format, leaving room for improvement in 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?

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional meaning beyond what's in the schema, such as examples or constraints not covered. With high schema coverage, the baseline is 3, and the description doesn't compensate with extra insights.

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's purpose: converting time between timezones. It specifies the verb 'convert' and the resource 'time', making it distinct from sibling tools like current_time or relative_time. However, it doesn't explicitly differentiate from all siblings (e.g., get_timestamp might involve timezone handling), so it's not a perfect 5.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, and it doesn't reference sibling tools like current_time or relative_time that might be used in similar time-related scenarios.

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

current_timeB

Get the current date and time.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatYesThe format of the time, default is empty stringYYYY-MM-DD HH:mm:ss
timezoneNoThe timezone of the time, IANA timezone name, e.g. Asia/Shanghai

TDQS

B3.1/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 of behavioral disclosure. It states 'Get the current date and time,' which implies a read-only operation, but doesn't mention any behavioral traits such as whether it requires authentication, has rate limits, or how it handles errors. For a tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence ('Get the current date and time.') that is front-loaded and wastes no words. It directly conveys the core purpose without unnecessary elaboration, making it highly concise and well-structured.

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?

Given the tool's low complexity (simple time retrieval) and high schema coverage (100%), the description is minimally adequate. However, with no annotations and no output schema, it doesn't fully compensate for the lack of behavioral context or return value information, leaving gaps that could hinder an agent's understanding of the tool's full behavior.

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 adds no parameter semantics beyond what the input schema provides. However, schema description coverage is 100%, with clear documentation for both parameters (format and timezone), including a default value and enum for format. This meets the baseline of 3, as the schema adequately covers parameter details without needing additional explanation in the description.

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 'Get the current date and time' clearly states the verb ('Get') and resource ('current date and time'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_timestamp' or 'relative_time', which might offer similar time-related functionality, so it doesn't reach the highest score.

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?

The description provides no guidance on when to use this tool versus alternatives like 'convert_time' or 'get_timestamp'. It lacks any context about use cases, prerequisites, or exclusions, leaving the agent to infer usage based on the tool name alone.

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

days_in_monthA

Get the number of days in a month. If no date is provided, get the number of days in the current month.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoThe date to get the days in month. Format: YYYY-MM-DD

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 of behavioral disclosure. It describes the default behavior (current month if no date) and the basic operation, but doesn't mention error handling, format validation for the date parameter, or what happens with invalid dates. It adds some context beyond the schema but lacks comprehensive behavioral traits.

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 appropriately sized with two clear, front-loaded sentences that directly state the tool's function and default behavior. There is zero waste or redundancy, and every sentence earns its place by providing essential information efficiently.

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?

Given the tool's low complexity (single optional parameter, simple calculation), no annotations, and no output schema, the description is reasonably complete. It covers the purpose, usage, and default behavior adequately, though it could benefit from mentioning error cases or output format to fully compensate for the lack of structured fields.

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 fully documents the single parameter 'date' with its format. The description adds marginal value by mentioning the default behavior (current month if no date provided), which implies the parameter is optional, but doesn't provide additional semantic details beyond what the schema specifies.

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 purpose with specific verbs ('Get the number of days in a month') and distinguishes it from siblings by focusing on month-day calculation rather than time conversion, timestamp retrieval, or relative time operations. It explicitly defines the resource (days in a month) and scope (current month if no date provided).

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 description provides clear context for when to use this tool (to get days in a month, with current month as default) but doesn't explicitly mention when not to use it or name alternatives among siblings like 'convert_time' or 'get_timestamp'. It implies usage for date-based month calculations but lacks explicit exclusions or comparisons.

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

get_timestampC

Get the timestamp for the time.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeNoThe time to get the timestamp. Format: YYYY-MM-DD HH:mm:ss

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It doesn't specify whether this is a pure function, what errors might occur (e.g., invalid format), what timezone is assumed, or what the output format is. The description mentions 'the timestamp' but doesn't define what that means operationally.

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 extremely concise at just 6 words, which could be appropriate for a simple tool. However, this brevity comes at the cost of clarity - it's under-specified rather than efficiently informative. The single sentence is front-loaded but doesn't provide enough substance.

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?

For a tool with no annotations, no output schema, and 1 parameter, the description is incomplete. It doesn't explain what a 'timestamp' output looks like, what transformations occur, or how this differs from sibling tools. The agent lacks sufficient information to understand what this tool actually produces or when to use it.

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%, with the single parameter 'time' documented as 'The time to get the timestamp' with format specification. The description adds no additional parameter semantics beyond what's in the schema. Since schema coverage is complete, the baseline score of 3 applies - adequate but no value added.

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

Purpose2/5

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

The description 'Get the timestamp for the time' is tautological - it essentially restates the tool name 'get_timestamp' without adding meaningful specificity. It doesn't explain what a 'timestamp' means in this context (e.g., Unix timestamp, ISO string, etc.) or what transformation occurs. While it mentions 'the time' as input, it doesn't clarify what the output represents.

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 provided about when to use this tool versus its siblings like 'convert_time' or 'current_time'. The description doesn't indicate whether this is for parsing human-readable times, converting between formats, or generating timestamps from date strings. Without usage context, an agent must infer from the name alone.

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

get_week_yearC

Get the week and isoWeek of the year.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoThe date to get the week and isoWeek of the year. e.g. 2025-03-23

TDQS

C2.9/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 of behavioral disclosure. It states the tool 'Get[s] the week and isoWeek of the year,' implying a read-only operation, but it doesn't disclose any behavioral traits such as error handling, format of return values, or performance considerations. For a tool with no annotation coverage, this is a significant gap in 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 extremely concise and front-loaded, consisting of a single sentence: 'Get the week and isoWeek of the year.' Every word earns its place, with no wasted information, making it easy for an agent to parse quickly and understand the core purpose without unnecessary detail.

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?

Given the tool's complexity (simple date calculation), the description is incomplete. There's no output schema, and the description doesn't explain return values (e.g., what 'week' and 'isoWeek' mean or their format). With no annotations and minimal behavioral context, the agent lacks sufficient information to fully understand how to use the tool effectively beyond basic input.

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 adds no parameter semantics beyond what the input schema provides. The schema has 100% description coverage, with the 'date' parameter fully documented, so the baseline score is 3. The description doesn't compensate with additional context, such as examples or constraints, but it doesn't need to since the schema is comprehensive.

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's purpose: 'Get the week and isoWeek of the year.' It specifies the verb ('Get') and the resource ('week and isoWeek of the year'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'convert_time' or 'get_timestamp', which might also handle date-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 Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions, and it doesn't reference sibling tools like 'convert_time' or 'get_timestamp' that might serve similar or overlapping purposes. This leaves the agent without clear usage instructions.

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

relative_timeB

Get the relative time from now.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeYesThe time to get the relative time from now. Format: YYYY-MM-DD HH:mm:ss

TDQS

B3.1/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 of behavioral disclosure. It states the tool 'gets' relative time, implying a read-only operation, but doesn't clarify if it's safe, has side effects, requires specific inputs beyond the schema, or how it handles errors. For a tool with no annotations, this is a significant gap in 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 a single, clear sentence: 'Get the relative time from now.' It is front-loaded with the core purpose, has zero waste, and is appropriately sized for a simple tool, making it highly concise and well-structured.

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?

Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks details on behavior, usage context, or output, which could be helpful for an agent. It meets the basic requirement but has clear gaps in 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?

The schema description coverage is 100%, with the parameter 'time' fully documented in the input schema. The description doesn't add any meaning beyond the schema, such as explaining the relative time calculation or output format. Since the schema does the heavy lifting, the baseline score 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's purpose: 'Get the relative time from now.' It specifies the verb ('get') and resource ('relative time'), making it understandable. However, it doesn't explicitly differentiate from siblings like 'convert_time' or 'current_time', which could handle similar time-related tasks, so it doesn't reach the highest score.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, exclusions, or comparisons to sibling tools like 'convert_time' or 'current_time', leaving the agent to infer usage based on the name alone.

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. 6 tool updates
    • First observedconvert_time
    • First observedcurrent_time
    • First observeddays_in_month
    • First observedget_timestamp
    • First observedget_week_year
    • First observedrelative_time

TDQS

B3.2/5.0

Scored across 6 tools

Disambiguation4/5

Most tools have distinct purposes, such as time conversion, current time retrieval, and timestamp generation. However, 'get_week_year' and 'relative_time' could be slightly ambiguous in scope, as both relate to temporal positioning, but their descriptions clarify the differences well.

Naming Consistency4/5

The tools follow a consistent verb_noun pattern (e.g., convert_time, current_time) with clear, descriptive names. There are minor deviations like 'days_in_month' using plural form, but overall, the naming is highly readable and predictable.

Tool Count5/5

With 6 tools, the server is well-scoped for time-related operations, covering core functionalities like conversion, current time, and date calculations. Each tool earns its place without feeling excessive or insufficient for the domain.

Completeness3/5

The toolset covers basic time operations but has notable gaps, such as missing date arithmetic (e.g., add/subtract days), time formatting, or scheduling tasks. While agents can work around this for simple queries, more complex time manipulations are not supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • 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
  • 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
  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides current time information and timezone conversion capabilities using IANA timezone names and automatic system detection. It enables LLMs to fetch current times across different regions and convert specific times between timezones.
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides current time and timezone conversion using IANA timezone names, enabling LLMs to get system time or convert times between timezones.
    MIT