NTP MCP Server 🕒

A Model Context Protocol (MCP) server that provides accurate time information from Network Time Protocol (NTP) servers with timezone support, security filtering, and structured output formatting.

🚀 Quick Start - Session Initialization

Start every AI conversation with:

This simple command syncs your AI assistant with accurate network time, ensuring correct timestamps throughout your session.

✨ Features

• 🌍 Multiple NTP Server Support: Connect to approved NTP servers worldwide

• 🔒 Security Filtering: Blocks unauthorized sources and untrusted domains

• 📋 Whitelist Approach: Only approved servers allowed for enhanced security

• 🕰️ Timezone Conversion: Automatic timezone conversion with pytz

• 📋 Structured Output Format: Clean, parseable time format

• 🔄 Fallback Mechanism: Falls back to local time if NTP is unavailable

• ⚡ Ultra-Fast Startup: UV package manager for instant dependency resolution

• ⚡ Retry Logic: Automatic retry with exponential backoff

• 🔧 Configurable: Environment variable configuration

• 📋 MCP Compatible: Works with Claude Desktop and other MCP clients

• 🧪 Security Testing: Comprehensive security validation

🔒 Security Features

This version includes enhanced security filtering:

• Geographic filtering for untrusted domains

• Blocks direct IP addresses for security

• Whitelist of approved servers including:

  • Global pools: pool.ntp.org, time.google.com, time.cloudflare.com

  • Regional pools: US, Europe, Asia, etc.

  • Major providers: NIST, Windows, Apple, Ubuntu

Use the list_approved_servers tool to see all approved servers.

🕐 Time Output Format

The NTP server outputs time in a structured, easy-to-parse format:

Example Outputs

Successful NTP Response:

Blocked Server Response:

🚀 Quick Start

What You'll Need

1. Python 3.11 or newer - The programming language this server runs on

   • Check if you have it: Open a terminal and type python --version

   • If you need it: Download from python.org

2. UV Package Manager - A fast, modern Python package installer (like npm for Node.js)

   • UV is faster and more reliable than pip

   • It handles dependencies and virtual environments automatically

   • Install UV with ONE of these commands:

     • Windows/Mac/Linux with pip: pip install uv

     • Mac/Linux with curl: curl -LsSf https://astral.sh/uv/install.sh | sh

3. Git (optional) - For cloning the repository

   • Or you can download the ZIP file from GitHub

Step-by-Step Installation

Option 1: Using Git (Recommended)

That's it! Claude will automatically start the NTP server when needed.

Option 2: Download ZIP

1. Go to https://github.com/jdez427/ntp-mcp

2. Click the green "Code" button → "Download ZIP"

3. Extract the ZIP file to a folder

4. Open a terminal in that folder

5. Run:

   uv sync # Optional: Configure timezone (default is UTC) chmod +x setup_timezone.sh && ./setup_timezone.sh # Then add to Claude: claude mcp add --scope user ntp bash /path/to/ntp-mcp/launch_ntpmcp.sh

What's Happening During Installation?

• uv sync reads the pyproject.toml file and:

  • Creates an isolated Python environment (so it won't affect other Python projects)

  • Downloads and installs all required packages (mcp, ntplib, pytz, etc.)

  • Locks the versions for consistency

• claude mcp add command:

  • Registers the NTP-MCP with Claude globally (--scope user)

  • Points to the launch script that Claude will use

  • Claude automatically starts/stops the server as needed

  • No manual server management required!

Local Installation

Environment Variables

• NTP_SERVER: NTP server to use (default: pool.ntp.org for dev, time.cloudflare.com for prod)

• TZ: Timezone for time display (default: system local or UTC)

📦 Installation for Claude Desktop

Method 1: Command Line (Recommended for Linux/WSL)

Method 2: Manual Configuration

If you prefer manual configuration or are on Windows/Mac without the CLI:

Finding Your Configuration File

Claude Desktop stores its configuration in different places depending on your operating system:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/claude/claude_desktop_config.json

Manual Setup

1. Open the configuration file in a text editor (Notepad, TextEdit, etc.)

2. Find or create the

3. Add the NTP-MCP configuration (see Configuration Format below)

Configuration Format

🔧 Available Tools

get_current_time

Get the current time from an approved NTP server.

Example:

list_approved_servers

List all approved NTP servers that can be used.

Example:

🐧 Systemd Service (Optional)

For automatic startup on Linux:

📝 Configuration

Claude Desktop (Windows)

Claude Desktop (Linux/Mac)

🧪 Testing the Server (Optional)

If you want to test the server manually before adding it to Claude:

Note: Manual testing is optional. Once added to Claude with claude mcp add, Claude handles all server management automatically.

🔧 Troubleshooting

Common Issues

"Command not found" or "uv not found"

• Make sure UV is installed: pip install uv

• On Windows, you might need to use python -m uv instead of just uv

"Permission denied" or "cannot execute: required file not found"

• On Mac/Linux: Run chmod +x launch_ntpmcp.sh to make it executable

• If you get "required file not found", the script may have Windows line endings

  • Fix with: sed -i 's/\r$//' launch_ntpmcp.sh

• On Windows: Use python launch_ntpmcp.sh instead

Claude doesn't recognize the time command

• Check your configuration file for syntax errors (missing commas, etc.)

• Make sure the path to ntp-mcp directory is correct

• Restart Claude Desktop completely (quit and reopen)

"Module not found" errors

• Run uv sync again to ensure all dependencies are installed

• Make sure you're in the ntp-mcp directory when running commands

Time shows wrong timezone

• Run the setup wizard: python setup_timezone.py

• Or manually set the TZ environment variable in the Claude config

📊 Performance

• Startup time: <1 second (UV optimization)

• Memory usage: <50MB

• Response time: <100ms (local region servers)

🛡️ Security Notes

• Geographic security filtering is enforced

• Direct IP addresses are not allowed

• Only whitelisted servers can be used

• Security patterns are regularly updated

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions welcome! Please ensure:

• Security filtering is maintained

• All tests pass

• UV package management is used

• Security best practices are followed

📞 Support

For issues or questions, please open an issue on GitHub.

🙏 Acknowledgments

This project was initially inspired by n3r0-b1n4ry/ntp-mcp-server, but has been completely redesigned and rewritten with enhanced security, performance optimizations, and production robustness.