Timezone

You have a dual-interface Timezone MCP Server that lets LLMs discover and use timezone data via MCP, while also offering a REST API for direct HTTP access. It provides regions, cities, and current time in any timezone with ISO 8601 timestamps, all secured with OAuth2 and accessible through both MCP and HTTP endpoints.

How to use

Connect with an MCP client to discover and call the available timezone tools. The server exposes tools to list regions, list cities within a region, and fetch current time data in ISO 8601 formats. For HTTP clients, use the REST API endpoints exposed under the base URL, and for MCP clients, use the MCP transport via HTTP/SSE or stdio as configured.

How to install

Prerequisites: install Node.js 22.20.0 or later and use pnpm as your package manager.

1. Install dependencies.

2. Set up environment variables for authentication and security.

Configuration and security

OAuth2 authentication is required for all endpoints except the health check. You will configure a JWT secret, OAuth2 provider details, and an allowlist of user emails in a local environment file.

Example environment variables you will set in the configuration file.

# Example environment configuration (copy to .env and edit)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRES_IN=3600

# OAuth2 provider (choose Google or GitHub or another compliant provider)
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

# User allowlist
ALLOWED_EMAILS=user1@example.com,user2@example.com,admin@company.com

Running and testing

You can run the MCP server either as a stdio-based local process or as an HTTP/MCP transport, depending on your integration needs.

To test the HTTP MCP endpoint locally, start the HTTP MCP server and then verify connectivity with your MCP client or the MCP Inspector.

Notes and troubleshooting

• Ensure the OAuth2 provider redirects are correctly configured to your localhost URL during development.

• If you modify environment variables, restart the server to apply changes.

Available tools

get_regions

Return the list of available timezone regions (e.g., Africa, America, Europe, etc.)

get_cities

Return the cities within a specified region (region input required)

get_timezone_info

Return current time data for a region/city with local and UTC timestamps in ISO 8601 formats