Time MCP Server

A Model Context Protocol (MCP) server that provides time and date information for AI assistants like Claude in VSCode.

Features

• Current Time: Get the current time in various formats
• Timezone Support: Query time in different timezones
• Detailed Info: Get comprehensive time information including day of week, timestamp, etc.
• Multiple Formats: Support for 12-hour, 24-hour, and ISO formats

Available Tools

get_current_time

Get the current date and time with formatting options.

Parameters:

• timezone (optional): Timezone identifier (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")
• format (optional): Time format - "12hour" (default), "24hour", or "iso"

Examples:

• "What time is it?"
• "Get current time in Tokyo"
• "Show me the time in 24-hour format"

get_time_info

Get detailed time information including timezone data, day of week, and timestamps.

Parameters:

• timezone (optional): Timezone identifier

Examples:

• "Give me detailed time information"
• "Show time info for London timezone"

Prerequisites

• Node.js (v18 or higher)
• npm
• Docker Desktop (for Docker builds)
  • Install via: brew install --cask docker
  • Or download from https://www.docker.com/products/docker-desktop/
  • Important: You need Docker Desktop (full app), not just Docker CLI

Installation

Local Development

1. Clone or create the project:

   mkdir time-mcp-server
   cd time-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Docker Deployment

Prerequisites: Ensure Docker Desktop is running

# Check Docker is running
docker ps

# If not running, start Docker Desktop
open -a Docker  # or open -a "Docker Desktop"

1. Build and run with Docker Compose:

   docker-compose up -d
   

2. Or build manually:

   docker build -t time-mcp-server .
   docker run -d --name time-mcp-server time-mcp-server
   

3. View logs:

   docker-compose logs -f time-mcp-server
   

Configuration

Configuration

Local Development - Claude in VSCode

For local Node.js execution:

{
  "servers": {
    "time-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {},
      "cwd": "."
    }
  }
}

Docker Deployment - Claude in VSCode

Option 1: Docker Exec (Recommended)

For a running Docker container:

{
  "servers": {
    "time-server": {
      "command": "docker",
      "args": ["exec", "-i", "time-mcp-server", "node", "dist/index.js"],
      "env": {}
    }
  }
}

Option 2: Docker Run (Creates new container each time)

{
  "servers": {
    "time-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "time-mcp-server"],
      "env": {}
    }
  }
}

Combined Configuration (Both Docker and Local)

Use this configuration to have both options available simultaneously:

{
  "servers": {
    "time-server-docker": {
      "command": "docker",
      "args": ["exec", "-i", "time-mcp-server", "node", "dist/index.js"],
      "env": {}
    },
    "time-server-local": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {},
      "cwd": "."
    }
  }
}

Benefits of combined configuration:

• ✅ Fallback options - If Docker is down, local still works
• ✅ Performance testing - Compare Docker vs local performance
• ✅ Development flexibility - Switch between deployment methods
• ✅ Redundancy - Multiple servers provide the same functionality

Note: Place your mcp.json file in the project root directory (same level as package.json) for relative paths to work correctly.

Configuration Steps

For Docker Setup:

1. Start your Docker container:

   docker-compose up -d
   

2. Verify container is running:

   docker ps | grep time-mcp-server
   

3. Update mcp.json with Docker configuration

For Local Setup:

1. Build the project:

   npm run build
   # or
   ./ci.sh
   

2. Place mcp.json in project root (same directory as package.json)

3. Test it works:

   npm test
   

For Combined Setup:

1. Ensure both are working (Docker container running + local build exists)
2. Place the mcp.json in your project root directory
3. Use the combined mcp.json configuration above

Testing Your Configuration

Test Docker version:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i time-mcp-server node dist/index.js

Test local version:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

Check logs:

# Docker logs
docker-compose logs -f time-mcp-server

# Local logs appear in terminal when running

Quick Start Guide

1. Build everything with CI script:

   chmod +x ci.sh
   ./ci.sh
   

2. For Docker deployment:

   # Ensure Docker Desktop is running
   docker ps
   
   # Build with Docker
   BUILD_TYPE=docker ./ci.sh
   
   # Start the container
   docker-compose up -d
   

3. Configure Claude in VSCode with appropriate mcp.json

Usage Examples

Once configured with Claude in VSCode, you can ask natural language questions:

• "What time is it?" → Returns current time
• "What time is it in New York?" → Returns time in EST/EDT
• "Show me the time in 24-hour format" → Returns time in 24-hour format
• "Get detailed time information" → Returns comprehensive time data
• "What day is today?" → Uses detailed info to show current day

Development

Project Structure

time-mcp-server/
├── src/
│   └── index.ts          # Main server code
├── dist/                 # Built JavaScript (generated)
├── ci.sh                 # CI/CD build script
├── Dockerfile            # Docker image definition
├── docker-compose.yml    # Docker orchestration
├── .dockerignore         # Docker build exclusions
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

Local Development Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Build and run the server (for MCP clients)
• npm start - Run the built server (for MCP clients)
• npm test - Quick test to verify server is working

CI/CD Build Script

Use the included ci.sh script for automated building and testing:

# Make executable (first time only)
chmod +x ci.sh

# Basic build and test
./ci.sh

# Docker build only
BUILD_TYPE=docker ./ci.sh

# Full build (local + Docker)
BUILD_TYPE=all ./ci.sh

# Skip tests
RUN_TESTS=false ./ci.sh

# Custom Docker tag
BUILD_TYPE=docker DOCKER_TAG=v1.0.0 ./ci.sh

# CI environment
CI=true ./ci.sh

CI Script Features:

• ✅ Prerequisite checking (Node.js, Docker)
• ✅ Automated building (TypeScript + Docker)
• ✅ Comprehensive testing (tool listing, function calls)
• ✅ Cross-platform compatibility (macOS/Linux)
• ✅ Color-coded output and error handling
• ✅ Build artifact generation

Testing

Quick Test:

npm test

Manual Testing:

# Test tool listing
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Test getting current time
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | node dist/index.js

Note: npm start and npm run dev will appear to "hang" - this is normal! The server is waiting for MCP protocol messages on stdin. Use the test commands above or configure with Claude to interact with it.

Supported Timezones

The server supports any valid IANA timezone identifier, including:

• America/New_York
• Europe/London
• Asia/Tokyo
• Australia/Sydney
• UTC

Dependencies

• @modelcontextprotocol/sdk - Official MCP SDK
• typescript - TypeScript compiler
• @types/node - Node.js type definitions

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test: npm run build
5. Submit a pull request

Troubleshooting

Common Issues

"No inputs were found" error:

• Ensure the src/index.ts file exists
• Run npm run build after creating the file

Docker not working:

• Ensure Docker Desktop is installed and running: brew install --cask docker
• Start Docker Desktop: open -a Docker (wait for whale icon in menu bar)
• Verify with: docker ps (should not show connection errors)
• Docker Desktop takes 30-60 seconds to fully start after launching

Server appears to hang:

• This is normal behavior! The server waits for MCP protocol messages on stdin
• Use npm test for quick verification, or configure with Claude for actual usage
• The server only responds when it receives proper JSON-RPC messages

TypeScript errors:

• Make sure all dependencies are installed: npm install
• Check TypeScript version compatibility

Debug Mode

Add console logging by setting environment variables:

{
  "servers": {
    "time-server": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Version History

• 0.1.0 - Initial release with basic time functionality