Time

What is the project about? Time (mcp-server-time) is a Model Context Protocol (MCP) server that provides current time information and timezone conversion capabilities to LLMs and other tooling. It exposes simple MCP tools so agents and editors can request the current time or convert times between IANA timezones with automatic system timezone detection.

How to use the project?

• Install/run:
  • Recommended (uvx): run uvx mcp-server-time.
  • Pip: pip install mcp-server-time then python -m mcp_server_time.
  • Docker: run the official image (e.g., docker run -i --rm -e LOCAL_TIMEZONE mcp/time).
• Configure as an MCP server in clients (examples provided for Claude, Zed, VS Code, Zencoder) by adding an mcpServers/context_servers entry pointing to the chosen command and args.
• Tools (RPC calls):
  • get_current_time: arguments: timezone (IANA name). Returns timezone, datetime (ISO), and is_dst.
  • convert_time: arguments: source_timezone, time (HH:MM 24-hour), target_timezone. Returns source and target datetimes and time_difference.
• Debugging: use the MCP inspector (npx @modelcontextprotocol/inspector uvx mcp-server-time) or run inspector against local code during development.

Key features

• get_current_time and convert_time MCP tools
• Uses IANA timezone names and detects system timezone by default
• Handles DST and returns ISO datetimes and DST flag
• Multiple deployment options: uvx, pip module, Docker image
• Easy integration with editors/agents (Claude, Zed, VS Code, Zencoder)
• Debuggable with MCP inspector
• MIT licensed and open to contributions

Use cases

1. Allow LLMs or chatbots to answer “what time is it now?” or “what time will it be in X timezone?”
2. Convert meeting times across timezones for scheduling assistants
3. Provide timezone-aware timestamps for logs, automated reports, or CI pipelines
4. Enrich context servers for editors/IDEs so tools can display or compute times consistently
5. Automated testing or transformation pipelines that require deterministic timezone conversions

FAQ

• How do I install it?

Use uvx mcp-server-time (recommended), or pip install mcp-server-time then python -m mcp_server_time, or run the Docker image mcp/time.

• How do I select or override the local/system timezone?

The server auto-detects system timezone by default. Override with the --local-timezone=Area/Location arg in the server command or set LOCAL_TIMEZONE env var for Docker.

• What timezone names and time formats are accepted?

Timezones must be valid IANA names (e.g., America/New_York). Times for convert_time use 24-hour HH:MM format.

• Does it handle DST?

Yes. Responses include an is_dst flag and the returned ISO datetimes reflect DST offsets.

• How do I integrate with Claude, Zed, or VS Code?

The repo includes example JSON snippets to add the server to each application’s MCP configuration (uvx, docker, pip variations).

• How can I debug the server?

Use the MCP inspector (npx @modelcontextprotocol/inspector) against uvx or your local development run; examples are in the README.

• What is the license?

MIT License.