Time Utilities MCP Server

Overview

Lightweight Python MCP server exposing date/time utilities (current time, time zone conversion, differences, addition). It is launched by time.mcp.yml using the mcp/time Docker image over STDIO.

Components

• main.py – registers the four time-related tools with FastMCP.
• time_calculator.py – core logic handling time zone arithmetic via zoneinfo, datetime, and tzlocal.
• pyproject.toml – lists dependencies (mcp, tzlocal).
• Dockerfile – two-stage Python 3.13 build that installs dependencies and runs python3 main.py as user mcp.

Exposed MCP tools

Tool	Purpose	Input
get_time_for_time_zone	Returns the current ISO timestamp in the requested IANA zone (defaults Europe/Madrid).	timezone.
convert_time_zone	Converts an HH:MM time from one zone to another, returning offsets.	time, origin_timezone, target_timezone.
calculate_time_difference	Computes HH:MM difference between two times.	origin_time, target_time.
add_time	Adds/subtracts a duration to an HH:MM time (years/months not supported).	time, optional years, months, days, hours, minutes, seconds.

All responses are dictionaries suitable for direct consumption by downstream agents.

Configuration

mcp_servers/time.mcp.yml defines the launch command:

time:
  transport: stdio
  command: docker
  args:
    - run
    - --init
    - -i
    - --rm
    - --network
    - buddai_net
    - mcp/time

No environment variables are required. The tool relies on the system’s timezone database; the base image includes the necessary data.

Running locally

1. Install Python ≥ 3.11 and pip install mcp==1.9.4 tzlocal==5.3.1.
2. Run python main.py to expose the STDIO interface.

Docker usage

docker build -t mcp/time mcp_servers/time

Then run:

docker network create buddai_net                  # once (shared infra)
docker run --rm --init -i \
  --network buddai_net \
  mcp/time

Development notes

• add_time intentionally raises if years or months are non-zero; extend the helper if you need calendar-aware arithmetic.
• convert_zone computes offsets in hours; fractional offsets display up to two decimals (e.g., +5.5h).

Troubleshooting

• KeyError: 'ZoneInfo': ensure the requested timezone is valid per the IANA database.
• DST anomalies: results depend on the current date; specify an explicit date/time if you need deterministic conversions (current implementation assumes “today”).