mcp-time

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

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:

# 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:

https://mcp.time.mcpcentral.io

Usage

Stdio Transport (Local)

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

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

Or with global installation:

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

Streamable HTTP Transport (Remote)

Configure your MCP client to use the remote HTTP endpoint:

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

Development

1. Clone the Repository:

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

2. Install Dependencies:

   npm install
   

3. Build: Compile the TypeScript code:

   npm run build
   

   (This compiles src/index.ts to dist/index.js)

4. Test Locally:

   Test Stdio Mode:

   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):

   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)

1. Configure Cloudflare:

   cp wrangler.toml.example wrangler.toml
   

   Edit wrangler.toml to configure your domain (optional).

2. Login and Deploy:

   wrangler login
   npx wrangler deploy
   

Publish to npm (Stdio Mode)

1. Build the package:

   npm run build
   

2. Publish:

   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:

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:

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:

1. Building a custom connector that links your MCP server to Copilot Studio
2. Adding the tool in Copilot Studio by selecting 'Add a Tool' and searching for your MCP server
3. 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

1. Start your server:

   # Local HTTP server
   npx wrangler dev
   
   # Or use deployed URL: https://mcp.time.mcpcentral.io
   

2. 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:

# 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:

// 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.