Timezone MCP Server

A dual-interface timezone server supporting both MCP (Model Context Protocol) for LLM discovery and REST API for direct HTTP access. Get available regions, cities, and current time in any timezone with ISO 8601 formatted timestamps.

Features

• 🤖 MCP Protocol Support - LLMs can auto-discover and use timezone tools via JSON-RPC
• 🌐 REST API - Traditional HTTP endpoints with Swagger/OpenAPI documentation
• 🔐 OAuth2 Authentication - Secure access with user allowlisting and client credentials
• ⏰ Timezone Operations - Get regions, cities, and current time in any timezone
• 📅 ISO 8601 Timestamps - Local datetime with offset, UTC datetime, and timezone offset
• 🧪 100% Test Coverage - Comprehensive unit and e2e tests (Vitest)
• 🔧 NestJS & TypeScript - Modern, type-safe development
• 📚 Dual Documentation - Swagger UI for humans, MCP schema for LLMs
• 🎨 Code Quality - ESLint, Prettier, and automated formatting

Getting Started

Prerequisites

• Node.js 22.20.0+ (LTS recommended)
• pnpm 10.13.1 (managed via Corepack)

📦 Package Manager: This project uses pnpm exclusively via Corepack (built into Node.js). The exact pnpm version is enforced by the packageManager field in package.json. After installing Node.js, run corepack enable to activate pnpm support.

🔧 Version Management: This project uses fnm (Fast Node Manager) or nvm to manage Node.js versions. The .node-version file will automatically switch to the correct Node.js version when you cd into the project directory (if you have fnm/nvm shell integration enabled).

Installation

pnpm install

Authentication Setup

This server requires OAuth2 authentication for all endpoints except /health. You need to configure authentication before running the server.

Step 1: Configure Environment Variables

Copy the example environment file and edit it:

cp example.env .env

Edit .env and configure:

1. JWT Settings (required):

   JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
   JWT_EXPIRES_IN=3600
   

2. OAuth2 Provider (choose one - Google, GitHub, or any OAuth2-compliant provider):

   For Google:

   OAUTH2_AUTHORIZATION_URL=https://accounts.google.com/o/oauth2/v2/auth
   OAUTH2_TOKEN_URL=https://oauth2.googleapis.com/token
   OAUTH2_USER_INFO_URL=https://www.googleapis.com/oauth2/v2/userinfo
   OAUTH2_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
   OAUTH2_CLIENT_SECRET=your-google-client-secret
   OAUTH2_CALLBACK_URL=http://localhost:3000/auth/callback
   OAUTH2_SCOPE=openid email profile
   

   For GitHub:

   OAUTH2_AUTHORIZATION_URL=https://github.com/login/oauth/authorize
   OAUTH2_TOKEN_URL=https://github.com/login/oauth/access_token
   OAUTH2_USER_INFO_URL=https://api.github.com/user
   OAUTH2_CLIENT_ID=your-github-client-id
   OAUTH2_CLIENT_SECRET=your-github-client-secret
   OAUTH2_CALLBACK_URL=http://localhost:3000/auth/callback
   OAUTH2_SCOPE=user:email
   

3. User Allowlist (required):

   ALLOWED_EMAILS=user1@example.com,user2@example.com,admin@company.com
   

Step 2: Set Up OAuth2 Provider

Create OAuth2 credentials with your provider:

• Google: Google Cloud Console
• GitHub: GitHub Developer Settings

Set the Authorized redirect URI to: http://localhost:3000/auth/callback

Step 3: Authentication Flow

1. Visit http://localhost:3000/auth/login
2. Redirected to OAuth2 provider (Google/GitHub/etc.)
3. Sign in and authorize
4. Redirected back with JWT token displayed on screen
5. Copy the token and use it in API requests:

   curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/timezones/regions
   

Running the Server

This project provides three interfaces that can run independently:

Option 1: MCP Server via stdio (for local LLM clients)

# Development mode with hot reload
pnpm mcp:dev

# Production mode
pnpm build
pnpm mcp:start

Uses stdio transport - launches as a subprocess. Perfect for Claude Desktop config file.

Option 2: MCP Server via HTTP (for remote LLM clients)

# Development mode with hot reload
pnpm mcp:http:dev

# Production mode
pnpm build
pnpm mcp:http

Uses Streamable HTTP over HTTP - accessible at http://localhost:3001/mcp

Perfect for Claude Desktop's "Add Custom Connector" UI! 🎯

Option 3: REST API Server (for HTTP clients)

# Development mode with hot reload
pnpm dev

# Production mode
pnpm build
pnpm start:prod

# Open Swagger UI in browser
pnpm swagger

The REST API will start on http://localhost:3000

Interactive Swagger/OpenAPI documentation is available at http://localhost:3000/api

Available Endpoints

Authentication:

• GET /auth/login - Initiate OAuth2 login (redirects to provider)
• GET /auth/callback - OAuth2 callback (returns JWT token)

Health:

• GET /health - Health check endpoint (public, no authentication required)

  {
    "status": "ok",
    "timestamp": "2025-10-17T18:30:45.123Z"
  }
  

Timezone API: (requires authentication - include Authorization: Bearer TOKEN header)

• GET /timezones/regions - Get all available timezone regions

  {
    "regions": [
      "Africa",
      "America",
      "Antarctica",
      "Asia",
      "Atlantic",
      "Australia",
      "Europe",
      "Indian",
      "Pacific"
    ],
    "count": 15
  }
  

• GET /timezones/regions/:region/cities - Get all cities in a specific region

  {
    "region": "America",
    "cities": ["New_York", "Los_Angeles", "Chicago", "Denver", "Phoenix"],
    "count": 150
  }
  

• GET /timezones/:region/:city - Get current time in a specific timezone

  {
    "timezone": "America/New_York",
    "datetime_local": "2025-10-17T13:47:23-04:00",
    "datetime_utc": "2025-10-17T17:47:23.345Z",
    "timezone_offset": "-04:00",
    "timestamp": 1760723243345
  }
  

MCP Protocol Integration

What is MCP?

Model Context Protocol (MCP) is a standardized protocol that allows LLMs to discover and use tools automatically. Instead of manually telling an LLM about your API endpoints, MCP-enabled clients like Claude Desktop can:

1. Auto-discover available tools via tools/list
2. Inspect schemas to understand input parameters
3. Execute tools via JSON-RPC tools/call requests

Testing with MCP Inspector (Quickest)

The MCP Inspector is a web UI for testing your MCP server without needing Claude Desktop:

pnpm install
pnpm build
pnpm mcp:inspector

This opens http://localhost:5173 where you can:

• See all 3 tools listed
• Inspect tool schemas and parameters
• Execute tools and see JSON responses
• Debug without installing anything else

Setting Up with Claude Desktop

Method 1: Local stdio Connection (Recommended)

1. Build the project:

   pnpm install
   pnpm build
   

2. Edit Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "timezone": {
         "command": "node",
         "args": ["/absolute/path/to/demo-mcp/dist/main.js"]
       }
     }
   }
   

3. Restart Claude Desktop

4. Claude can now auto-discover and use the timezone tools!

Available MCP Tools

Tool	Parameters	Description
get_regions	None	Get list of all timezone regions
get_cities	region: string	Get cities in a specific region
get_timezone_info	region: string<br/>city: string	Get current time with ISO 8601 formats

Architecture

┌───────────────────────────────────────────────────┐
│              Timezone MCP Server                  │
├───────────────────────────────────────────────────┤
│                                                   │
│  REST API        MCP (HTTP/SSE)      MCP (stdio)  │
│  Port 3000       Port 3001           subprocess   │
│      ↓                ↓                   ↓       │
│  ┌────────┐     ┌─────────┐         ┌─────────┐   │
│  │NestJS  │     │   MCP   │         │   MCP   │   │
│  │ HTTP   │     │  HTTP   │         │  stdio  │   │
│  └───┬────┘     └────┬────┘         └────┬────┘   │
│      │               │                   │        │
│      └───────────────┴───────────────────┘        │
│                      ↓                            │
│              TimezoneService                      │
│          (Shared Business Logic)                  │
└───────────────────────────────────────────────────┘

All three interfaces use the same TimezoneService, ensuring consistent behavior across REST API, remote MCP, and local MCP connections.

Testing

# Run all tests (includes MCP stdio e2e tests)
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:cov

# Run tests with UI
pnpm test:ui

# Run e2e tests only
pnpm test:e2e

Test Coverage: 103/109 tests passing (94.5%). The HTTP MCP transport has comprehensive manual testing via MCP Inspector but automated e2e tests are pending due to SSE timing complexity.

Manual Testing HTTP MCP Server:

# Start HTTP MCP server
pnpm mcp:http:dev

# Test with MCP Inspector
pnpm mcp:inspector

# Test with Claude Desktop
# Settings > Connectors > Add Custom Connector
# URL: http://localhost:3001/mcp

Code Quality

# Lint code
pnpm lint

# Fix lint issues
pnpm lint:fix

# Format code
pnpm format

# Check formatting
pnpm format:check

Documentation

Additional guides and documentation are available in the docs/ directory:

• Local Testing Guide - Step-by-step instructions for testing with MCP Inspector
• Deployment Guide - Deploy to Google Cloud Run
• Deployment Success Guide - Post-deployment verification

Scripts Reference

Server Scripts

• pnpm dev - Start REST API server in development mode
• pnpm start - Start REST API server
• pnpm start:prod - Start REST API server in production mode
• pnpm mcp:dev - Start MCP server (stdio) in development mode
• pnpm mcp:start - Start MCP server (stdio) in production mode
• pnpm mcp:http:dev - Start MCP server (HTTP/SSE) in development mode
• pnpm mcp:http - Start MCP server (HTTP/SSE) in production mode
• pnpm mcp:inspector - Start MCP Inspector (debug/test MCP tools in browser)
• pnpm swagger - Open Swagger UI in default browser

Build & Test

• pnpm build - Build the project (compiles TypeScript to dist/)
• pnpm test - Run all tests (84 tests including MCP e2e)
• pnpm test:watch - Run tests in watch mode
• pnpm test:cov - Run tests with coverage report (100% coverage)
• pnpm test:ui - Run tests with Vitest UI
• pnpm test:e2e - Run end-to-end tests only

Code Quality

• pnpm lint - Lint code with ESLint
• pnpm lint:fix - Fix linting issues automatically
• pnpm format - Format code with Prettier
• pnpm format:check - Check if code is properly formatted
• deps:check - Check if dependencies can be upgraded (minor/patch only)
• deps:update - Upgrade dependencies (minor/patch only)