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:

"What time is it?"
"Sync time"

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:

Date:YYYY-MM-DD
Time:HH:mm:ss
Timezone:timezone_name
NTP Server:server_name

Example Outputs

Successful NTP Response:

Date:2025-08-29
Time:14:30:25
Timezone:UTC
NTP Server:time.cloudflare.com

Blocked Server Response:

Security Error: Server 'ntp.ru' blocked: matches pattern '\.ru$'

Please use one of the approved servers. Use 'list_approved_servers' tool to see the list.

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

# 1. Clone (download) the repository
git clone https://github.com/jdez427/ntp-mcp.git

# 2. Enter the project directory
cd ntp-mcp

# 3. Let UV install all dependencies
#    This creates a virtual environment and installs everything needed
uv sync

# 4. (Optional) Configure your timezone
#    By default, NTP-MCP uses UTC. To use your local timezone:
./setup_timezone.sh
# Or: python3 setup_timezone.py
# Note: You may need to make scripts executable first:
# chmod +x setup_timezone.sh launch_ntpmcp.sh

# 5. Add the MCP to Claude (global installation)
#    This makes it available to all Claude instances
claude mcp add --scope user ntp bash /path/to/ntp-mcp/launch_ntpmcp.sh

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

# Install to local directory
mkdir -p ~/ntp-mcp
cp -r src pyproject.toml launch_ntpmcp.sh ~/ntp-mcp/
cd ~/ntp-mcp
uv sync

# Add to Claude globally
claude mcp add --scope user ntp bash ~/ntp-mcp/launch_ntpmcp.sh

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)

# Global installation for all Claude instances
claude mcp add --scope user ntp bash /path/to/ntp-mcp/launch_ntpmcp.sh

# Verify it's connected
claude mcp list

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 mcpServers section
3. Add the NTP-MCP configuration (see Configuration Format below)

Configuration Format

{
  "mcpServers": {
    "ntp-server": {
      "command": "uv",
      "args": ["run", "python", "-m", "ntp_mcp"],
      "cwd": "/path/to/ntp-mcp",
      "env": {
        "NTP_SERVER": "time.cloudflare.com",
        "TZ": "UTC"
      }
    }
  }
}

🔧 Available Tools

get_current_time

Get the current time from an approved NTP server.

Example:

{
  "tool": "get_current_time",
  "arguments": {}
}

list_approved_servers

List all approved NTP servers that can be used.

Example:

{
  "tool": "list_approved_servers",
  "arguments": {}
}

🐧 Systemd Service (Optional)

For automatic startup on Linux:

# Copy service file
sudo cp /path/to/ntp-mcp/ntp-mcp.service /etc/systemd/system/

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable ntp-mcp
sudo systemctl start ntp-mcp

# Check status
sudo systemctl status ntp-mcp

📝 Configuration

Claude Desktop (Windows)

{
  "mcpServers": {
    "ntp-server": {
      "command": "wsl",
      "args": ["-e", "bash", "-c", "cd /path/to/ntp-mcp && uv run python -m ntp_mcp"],
      "env": {
        "NTP_SERVER": "time.cloudflare.com",
        "TZ": "America/New_York"
      }
    }
  }
}

Claude Desktop (Linux/Mac)

{
  "mcpServers": {
    "ntp-server": {
      "command": "/path/to/ntp-mcp/.venv/bin/python",
      "args": ["-m", "ntp_mcp"],
      "env": {
        "NTP_SERVER": "time.cloudflare.com",
        "TZ": "UTC"
      }
    }
  }
}

🧪 Testing the Server (Optional)

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

# Run the server manually (Ctrl+C to stop)
./launch_ntpmcp.sh

# In another terminal, you can test it with:
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "test", "version": "1.0"}, "capabilities": {}}, "id": 1}' | uv run python -m ntp_mcp

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.