PierreGode/timeMCP

MCP Time Server

A Model Context Protocol (MCP) server that provides time and date functionality. This server exposes tools for getting current time, date, and formatting timestamps in various formats and timezones.

Features

• get_current_time: Get current time in ISO, local, UTC, or Unix timestamp format
• get_current_date: Get current date in various formats (ISO, local, short, long, custom)
• get_datetime_info: Get comprehensive date/time information including timezone details
• format_timestamp: Format any Unix timestamp to readable formats

Installation

1. clone MCP server:

git clone https://github.com/PierreGode/timeMCP.git
cd timeMCP

2. Save the server code as timeserver.js and the package configuration as package.json

3. Install dependencies:

npm install

4. If in Linux Make the server executable:

chmod +x timeserver.js

Usage

Running the Server

The server runs on stdio transport (standard input/output):

node timeserver.js

To run the server, you need to add it to your MCP configuration. For example, if you are using Claude Desktop, you can do this by modifying the claude_desktop_config.json file, for some reason Claude might not recognize the server untill you reinstall the claude desktop app, so you might need to do that after adding the server.

Example Configuration for Claude Desktop

edit claude_desktop_config.json
```bash
{
  "mcpServers": {
    "time-server": {
      "command": "node",
      "args": ["C:\\Users\\youruser\\Documents\\timeMCP\\timeserver.js"],
      "env": {}
    }
  }
}

Available Tools

1. get_current_time

Get the current time in various formats.

Parameters:

• format (optional): "iso", "local", "utc", or "unix" (default: "iso")
• timezone (optional): Timezone string like "America/New_York" (default: "local")

Example:

{
  "format": "local",
  "timezone": "Europe/London"
}

2. get_current_date

Get the current date in various formats.

Parameters:

• format (optional): "iso", "local", "short", "long", or "custom" (default: "iso")
• customFormat (optional): JSON string of Intl.DateTimeFormat options (when format is "custom")
• timezone (optional): Timezone string (default: "local")

Example:

{
  "format": "long",
  "timezone": "Asia/Tokyo"
}

3. get_datetime_info

Get comprehensive date and time information.

Parameters:

• timezone (optional): Timezone string (default: "local")

Example:

{
  "timezone": "America/Los_Angeles"
}

4. format_timestamp

Format a Unix timestamp.

Parameters:

• timestamp (required): Unix timestamp in milliseconds
• format (optional): "iso", "local", "utc", or "custom" (default: "iso")
• timezone (optional): Timezone string (default: "local")

Example:

{
  "timestamp": 1703097600000,
  "format": "local",
  "timezone": "UTC"
}

Integration with MCP Clients

To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "time-server": {
      "command": "node",
      "args": ["/path/to/your/mcp-time-server/server.js"],
      "env": {}
    }
  }
}

Other MCP Clients

For other MCP clients, refer to their documentation on how to configure MCP servers. The server uses stdio transport and follows the standard MCP protocol.

Example Responses

Current Time (ISO format):

Current time (iso): 2024-12-20T14:30:45.123Z

Current Date (long format):

Current date (long): Friday, December 20, 2024

DateTime Info:

{
  "timestamp": 1703097845123,
  "iso": "2024-12-20T14:30:45.123Z",
  "local": "12/20/2024, 2:30:45 PM",
  "utc": "Fri, 20 Dec 2024 14:30:45 GMT",
  "unix": 1703097845,
  "year": 2024,
  "month": 12,
  "day": 20,
  "hour": 14,
  "minute": 30,
  "second": 45,
  "dayOfWeek": "Friday",
  "timezone": "America/New_York"
}

Development

To run in development mode with debugging:

npm run dev

Error Handling

The server includes comprehensive error handling for:

• Invalid timezones
• Invalid timestamps
• Malformed custom format strings
• Missing required parameters

License

MIT License