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

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

Go to https://github.com/jdez427/ntp-mcp
Click the green "Code" button → "Download ZIP"
Extract the ZIP file to a folder
Open a terminal in that folder

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

Open the configuration file in a text editor (Notepad, TextEdit, etc.)
Find or create the mcpServers section
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.

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

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

Go to https://github.com/jdez427/ntp-mcp
Click the green "Code" button → "Download ZIP"
Extract the ZIP file to a folder
Open a terminal in that folder

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

Open the configuration file in a text editor (Notepad, TextEdit, etc.)
Find or create the mcpServers section
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.