io.github.mcpcentral-io/mcp-time

Official

by mcpcentral-io · JavaScript

Time MCP server via HTTP

HTTP-based MCP server providing time and date functionality.

README.md9 KBView on GitHub

MCP Time Server

A Model Context Protocol (MCP) server providing time-related tools with dual-mode support:

Stdio transport for local MCP clients (via npm)
Streamable HTTP transport for remote access (via Cloudflare Workers)

This server allows LLMs to access various date/time functions through multiple connection methods.

MCP Central Server Card: https://guide-gen.mcpcentral.io/servers/io-github-mcpcentral-io-mcp-time

Features

Provides the following MCP tools:

current_time: Get the current date and time in specified formats and timezones.
relative_time: Get a human-readable relative time string (e.g., "in 5 minutes", "2 hours ago").
days_in_month: Get the number of days in a specific month.
get_timestamp: Get the Unix timestamp (milliseconds) for a given time.
convert_time: Convert a time between different IANA timezones.
get_week_year: Get the week number and ISO week number for a given date.

Project Structure

code

mcp-time/
├── src/
│   └── index.ts      # Cloudflare Worker entry point & MCP logic
├── package.json      # Project dependencies and scripts
├── tsconfig.json     # TypeScript configuration
└── wrangler.toml     # Cloudflare Worker configuration

Installation

Option 1: Install from npm (Stdio Mode)

Install the package globally or use with npx:

bash

# Global installation
npm install -g @mcpcentral/mcp-time

# Or use directly with npx
npx @mcpcentral/mcp-time

Option 2: Use Remote Server (HTTP Mode)

Connect directly to the deployed Cloudflare Worker:

Example:

code

https://mcp.time.mcpcentral.io

Usage

Stdio Transport (Local)

Configure your MCP client (e.g., Claude Desktop) to use the stdio transport:

json

{
  "mcpServers": {
    "time-server": {
      "command": "npx",
      "args": ["@mcpcentral/mcp-time"]
    }
  }
}

Or with global installation:

json

{
  "mcpServers": {
    "time-server": {
      "command": "/path/to/node/bin/mcp-time"
    }
  }
}

Streamable HTTP Transport (Remote)

Configure your MCP client to use the remote HTTP endpoint:

json

{
  "mcpServers": {
    "time-server": {
      "url": "https://mcp.time.mcpcentral.io",
      "transport": "streamable-http"
    }
  }
}

Development

Clone the Repository:

bash

git clone https://github.com/mcpcentral-io/mcp-time.git
cd mcp-time

Install Dependencies:
bash
```
npm install
```
Build: Compile the TypeScript code:
bash
```
npm run build
```
(This compiles src/index.ts to dist/index.js)

Test Locally:

Test Stdio Mode:

bash

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

Test HTTP Mode (via Wrangler):

bash

npx wrangler dev

This will start the server on http://localhost:8787. You can then test with curl or point your MCP client to this local endpoint.

Deployment

Deploy to Cloudflare Workers (HTTP Mode)

Configure Cloudflare:
bash
```
cp wrangler.toml.example wrangler.toml
```
Edit wrangler.toml to configure your domain (optional).
Login and Deploy:
bash
```
wrangler login
npx wrangler deploy
```

Publish to npm (Stdio Mode)

Build the package:
bash
```
npm run build
```
Publish:
bash
```
npm publish --access public
```

Connectors for Streamable HTTP Servers

NEW: Major providers have adopted the Model Context Protocol and now support Streamable HTTP servers directly. Anthropic, OpenAI, and Microsoft have all adopted this modern transport protocol.

📋 Protocol Note: Streamable HTTP is the modern replacement for the deprecated HTTP+SSE transport.

Anthropic MCP Connector

Anthropic's MCP Connector allows you to use Streamable HTTP servers directly through the Messages API without needing a separate MCP client.

The MCP Connector is perfect for this server since it uses the Streamable HTTP architecture. Simply include the server in your API requests:

bash

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-04-04" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1000,
    "messages": [{
      "role": "user", 
      "content": "What time is it in Tokyo?"
    }],
    "mcp_servers": [{
      "type": "url",
      "url": "https://your.worker.url.workers.dev",
      "name": "http-time-server"
    }]
  }'

Anthropic MCP Connector Benefits:

No client setup required - Connect directly through the API
Native Streamable HTTP support - Designed for servers like this one

OpenAI Agents SDK

OpenAI also supports Streamable HTTP servers through their Agents SDK using the MCPServerStreamableHttp class:

python

from agents.mcp.server import MCPServerStreamableHttp

# Connect to this Streamable HTTP server
server = MCPServerStreamableHttp({
    "url": "https://your.worker.url.workers.dev",
    "headers": {"Authorization": "Bearer your-token"},  # if needed
})

# Use the server in your OpenAI agent
await server.connect()
tools = await server.list_tools()
result = await server.call_tool("current_time", {"timezone": "Asia/Tokyo"})

Microsoft Copilot Studio

Microsoft Copilot Studio now supports Streamable HTTP servers with MCP integration generally available. You can connect this server to Copilot Studio by:

Building a custom connector that links your MCP server to Copilot Studio
Adding the tool in Copilot Studio by selecting 'Add a Tool' and searching for your MCP server
Using the server directly in your agents with generative orchestration enabled

More MCP Clients Coming Soon

Keep an eye out as more MCP clients adopt support for Streamable HTTP. Here are a few resources that maintain lists of MCP clients and their capabilities:

PulseMCP Client Directory - Comprehensive list of MCP clients
Official MCP Servers Repository - Official collection including client information
MCP.so Client Listings - Community-maintained client directory

Testing and Validation

MCP Inspector Tools (HTTP Mode)

Test your server using these web-based inspection tools:

MCPCentral Tools (Recommended)

MCPCentral Lab - Interactive testing environment for MCP servers
MCPCentral Inspector - Streamable HTTP server inspector

Official MCP Inspector

The official MCP Inspector is also available:

Visit: https://github.com/modelcontextprotocol/inspector
Or run: npx @modelcontextprotocol/inspector

Testing Steps

Start your server:

bash

# Local HTTP server
npx wrangler dev

# Or use deployed URL: https://mcp.time.mcpcentral.io

Connect with an inspector:
- Transport: Streamable HTTP
- URL: http://localhost:8787 or https://mcp.time.mcpcentral.io
- Click Connect

Command Line Testing (Stdio Mode)

Test the stdio transport directly:

bash

# Test initialization
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npx @mcpcentral/mcp-time

# Test tool call
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"current_time","arguments":{"timezone":"America/New_York"}}}' | npx @mcpcentral/mcp-time

Available Tools to Test

The inspector will show all six time-related tools:

current_time: Test with different timezones (e.g., "America/New_York", "Europe/London")
relative_time: Test with various time strings (e.g., "2024-12-25T00:00:00Z")
days_in_month: Test with different months and years
get_timestamp: Convert date-time strings to Unix timestamps
convert_time: Convert between different timezones
get_week_year: Get week numbers for specific dates

Example Test Cases

Try these test cases in the inspector:

json

// current_time
{"timezone": "Asia/Tokyo", "format": "iso"}

// relative_time  
{"time": "2024-12-25T00:00:00Z"}

// days_in_month
{"month": 2, "year": 2024}

// get_timestamp
{"time": "2024-06-15T12:00:00Z"}

// convert_time
{"time": "2024-06-15T12:00:00", "from": "UTC", "to": "America/Los_Angeles"}

// get_week_year
{"date": "2024-06-15"}

Validation Checklist

Use the inspector to verify:

✅ Server connects successfully
✅ All 6 tools are listed
✅ Tool schemas are properly defined
✅ Tools execute without errors
✅ Results are formatted correctly
✅ Error handling works for invalid inputs

The MCP Inspector provides the most comprehensive way to test your server before integrating it with AI clients.

Authentication & Security Considerations

⚠️ IMPORTANT: This example server has NO authentication or security measures implemented.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-time": {
      "command": "npx",
      "args": [
        "-y",
        "@mcpcentral/mcp-time@0.0.3"
      ]
    }
  }
}