Time MCP Server: Time and Timezone Management for LLMs

The Time MCP Server is a specialized implementation of the Model Context Protocol (MCP) designed to provide time and timezone conversion capabilities. This server enables Large Language Models (LLMs) to retrieve current time information and perform accurate timezone conversions using IANA timezone names, with automatic system timezone detection.

Key Features

• Current Time Retrieval: Fetch the current time in any specified timezone or the system’s default timezone.
• Timezone Conversion: Convert time between different timezones with precision.
• Automatic Timezone Detection: The server automatically detects the system’s timezone, ensuring accurate results.

Available Tools

get_current_time

Retrieves the current time in a specified timezone or the system’s default timezone.

Required Arguments:
- timezone (string): IANA timezone name (e.g., America/New_York, Europe/London).

convert_time

Converts a specific time from one timezone to another.

Required Arguments:
- source_timezone (string): Source IANA timezone name.
- time (string): Time in 24-hour format (HH:MM).
- target_timezone (string): Target IANA timezone name.

Installation

Using uv (Recommended)

No specific installation is required when using uv. Use uvx to run mcp-server-time directly.

Using pip

Install mcp-server-time via pip:

pip install mcp-server-time

Run the server as a script:

python -m mcp_server_time

Configuration

For Claude.app

Add the following to your Claude settings:

Using uvx

"mcpServers": {
  "time": {
    "command": "uvx",
    "args": ["mcp-server-time"]
  }
}

Using Docker

"mcpServers": {
  "time": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "mcp/time"]
  }
}

Using pip Installation

"mcpServers": {
  "time": {
    "command": "python",
    "args": ["-m", "mcp_server_time"]
  }
}

For Zed

Add the following to your settings.json:

Using uvx

"context_servers": {
  "mcp-server-time": {
    "command": "uvx",
    "args": ["mcp-server-time"]
  }
}

Using pip Installation

"context_servers": {
  "mcp-server-time": {
    "command": "python",
    "args": ["-m", "mcp_server_time"]
  }
}

Customization - System Timezone

Override the default system timezone detection by adding the --local-timezone argument:

{
  "command": "python",
  "args": ["-m", "mcp_server_time", "--local-timezone=America/New_York"]
}

Example Interactions

Get Current Time

{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Europe/Warsaw"
  }
}

Response:

{
  "timezone": "Europe/Warsaw",
  "datetime": "2024-01-01T13:00:00+01:00",
  "is_dst": false
}

Convert Time Between Timezones

{
  "name": "convert_time",
  "arguments": {
    "source_timezone": "America/New_York",
    "time": "16:30",
    "target_timezone": "Asia/Tokyo"
  }
}

Response:

{
  "source": {
    "timezone": "America/New_York",
    "datetime": "2024-01-01T12:30:00-05:00",
    "is_dst": false
  },
  "target": {
    "timezone": "Asia/Tokyo",
    "datetime": "2024-01-01T12:30:00+09:00",
    "is_dst": false
  },
  "time_difference": "+13.0h"
}

Debugging

Use the MCP inspector for debugging:

For uvx Installations

npx @modelcontextprotocol/inspector uvx mcp-server-time

For Local Development

cd path/to/servers/src/time
npx @modelcontextprotocol/inspector uv run mcp-server-time

Example Questions for Claude

1. "What time is it now?" (uses system timezone)
2. "What time is it in Tokyo?"
3. "When it's 4 PM in New York, what time is it in London?"
4. "Convert 9:30 AM Tokyo time to New York time."

Build

Docker Build

cd src/time
docker build -t mcp/time .

Contributing

We welcome contributions to enhance mcp-server-time. Whether you want to add new features, improve functionality, or update documentation, your input is valuable.

For examples of other MCP servers, visit: https://github.com/modelcontextprotocol/servers.

License

mcp-server-time is licensed under the MIT License. For more details, see the LICENSE file in the repository.