MCP Time Server (mcp-time-srv)

A simple Model Context Protocol (MCP) server implemented in TypeScript that provides tools for time-related queries, including getting the current time in various timezones and converting times between timezones.

This server supports both modern Streamable HTTP and legacy HTTP+SSE MCP transport protocols.

Features

Provides the following MCP tools:

• get_current_time: Returns the current time in a specified IANA timezone.
• convert_time: Converts a given time from a source IANA timezone to a target IANA timezone.

Prerequisites

• Node.js (v18 or later recommended)
• npm (usually comes with Node.js)
• Docker (Optional, for running in a container)

Setup

1. Clone the repository (if you haven't already):

   # git clone <your-repo-url>
   # cd mcp-time-srv
   

2. Install dependencies:

   npm install
   

Running Locally

1. Build the TypeScript code:

   npm run build
   

   This compiles the TypeScript source in src/ to JavaScript in dist/.

2. Run the server: You can run the server using ts-node (for development) or directly with node after building.

   • Using ts-node:

     npx ts-node src/server.ts
     

   • Using node (after building):

     node dist/server.js
     

The server will start, typically listening on port 3000.

MCP Time server listening on http://localhost:3000

Running with Docker (Optional)

A Dockerfile is provided for building and running the server in a container.

1. Build the Docker image:

   docker build -t mcp-time-srv .
   

2. Run the container:

   docker run -d -p 3000:3000 --name my-mcp-server mcp-time-srv
   

   • -d: Run in detached mode (in the background).
   • -p 3000:3000: Map port 3000 on your host to port 3000 in the container.
   • --name my-mcp-server: Assign a name to the container for easier management.

The server will be running inside the container, accessible at http://localhost:3000.

To stop the container:

docker stop my-mcp-server

To view logs:

docker logs my-mcp-server

Testing with the Client

A simple test client script (src/client.ts) is included to demonstrate interacting with the server's tools.

1. Ensure the server is running (either locally or in Docker).
2. Run the client:

   npx ts-node src/client.ts
   

The client will connect to the server (using SSE transport by default), list the available tools, call each tool with example arguments (including some designed to test error handling), and print the results.

Tool Details

get_current_time

Returns the current time in the specified timezone.

• Input Argument:
  • timezone (string, optional): An IANA timezone name (e.g., America/New_York, Europe/London). If omitted, defaults to the server's local timezone.
• Output: A JSON object containing:
  • timezone (string): The effective timezone used.
  • datetime (string): The current time in ISO 8601 format with offset (e.g., 2025-04-26T01:39:15Z).

convert_time

Converts a time from a source timezone to a target timezone.

• Input Arguments:
  • source_timezone (string, optional): Source IANA timezone name. Defaults to server's local timezone if omitted.
  • time (string, required): The time to convert in 24-hour HH:MM format (e.g., 14:30).
  • target_timezone (string, optional): Target IANA timezone name. Defaults to server's local timezone if omitted.
• Output: A JSON object containing:
  • source (object): Details of the time in the source timezone (timezone, datetime).
  • target (object): Details of the converted time in the target timezone (timezone, datetime).
  • time_difference (string): The difference between the target and source timezone offsets (e.g., +8h, -5h, +5.75h).

License

This project is licensed under the MIT License - see the LICENSE file for details.