mcp-time-server

FoxLauren/mcp-time-server

3.2

If you are the rightful owner of mcp-time-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A lightweight, cross-platform MCP server providing time and date utilities using Python's standard library.

Tools
8
Resources
0
Prompts
0

MCP Time Server

A lightweight, cross-platform MCP (Model Context Protocol) server that provides simple time and date utilities using only Python's standard library.

Features

  • Get current time in any timezone
  • Parse and validate datetime strings
  • Compare times and calculate differences
  • Add/subtract time from dates
  • Convert Unix timestamps to readable dates
  • List and query timezones
  • Cross-platform (Windows, macOS, Linux)
  • Zero external dependencies (except FastMCP)
  • Compilable to standalone executables

Available Tools

get_current_time(tz: Optional[str])

Get the current date and time, optionally in a specific timezone.

get_timezone_info(tz: str)

Get detailed information about a timezone including current time and offset.

list_timezones(filter_text: Optional[str])

List all available timezones, optionally filtered by text.

parse_datetime(date_string: str, format_string: str)

Parse a datetime string and return detailed information.

compare_times(time1: str, time2: str, format_string: str)

Compare two datetime strings and calculate the difference.

add_time_delta(base_time: str, days: int, hours: int, minutes: int, seconds: int, format_string: str)

Add or subtract time from a given datetime.

is_valid_datetime(date_string: str, format_string: str)

Validate whether a string matches a datetime format.

unix_to_datetime(timestamp: int, tz: Optional[str])

Convert a Unix timestamp to a readable datetime.

Installation

Option 1: Download Pre-built Executables (Recommended)

Download the latest release for your platform from the page:

  • Windows: mcp-time-server-windows.exe
  • macOS: mcp-time-server-macos (Apple Silicon)
  • Linux: mcp-time-server-linux (x86_64)
Windows Setup
  1. Download mcp-time-server-windows.exe from the releases page
  2. Save it to a permanent location (e.g., C:\Users\YourName\mcp-servers\)
  3. Windows may show a security warning - click "More info" then "Run anyway" (the executable is safe, but unsigned)
  4. The executable is ready to use - no installation required!
macOS Setup
  1. Download mcp-time-server-macos from the releases page
  2. Save it to a permanent location (e.g., ~/mcp-servers/)
  3. Make the file executable: 
    chmod +x mcp-time-server-macos
  4. First time running: macOS Gatekeeper will block the unsigned executable:
    • Try to run the executable (or add it to Claude Desktop config and restart Claude)
    • macOS will show "cannot be opened because the developer cannot be verified"
    • Open System Settings → Privacy & Security
    • Scroll down to the Security section
    • Click "Allow Anyway" next to the message about mcp-time-server-macos
    • Try running again - click "Open" when prompted
  5. The executable is now trusted and ready to use!
Linux Setup
  1. Download mcp-time-server-linux from the releases page
  2. Save it to a permanent location (e.g., ~/mcp-servers/)
  3. Make the file executable: 
    chmod +x mcp-time-server-linux
  4. The executable is ready to use!

Option 2: Run from Source

  1. Clone or download this repository
  2. Install dependencies:
pip install mcp

For development and building:

pip install mcp pyinstaller

Running the Server

Standard Mode
python server.py
As MCP Server with Claude Desktop
Windows

  1. Open your Claude Desktop config file at:

    %APPDATA%\Claude\claude_desktop_config.json

    Or navigate to: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

  2. Add the MCP server configuration (use the full path where you saved the executable):

    {
  "mcpServers": {
    "time": {
      "command": "C:\\Users\\YourName\\mcp-servers\\mcp-time-server-windows.exe"
    }
  }
}

    Important: Use double backslashes (\\) in Windows paths!

  3. Restart Claude Desktop completely (quit and reopen)

  4. The time server tools should now be available in Claude Desktop

macOS

  1. Open your Claude Desktop config file at:

    ~/Library/Application Support/Claude/claude_desktop_config.json

  2. Add the MCP server configuration:

    Using the executable:

    {
  "mcpServers": {
    "time": {
      "command": "/absolute/path/to/mcp-time-server-macos"
    }
  }
}

    Using Python:

    {
  "mcpServers": {
    "time": {
      "command": "/usr/local/bin/python3",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

  3. Restart Claude Desktop completely (quit and reopen)

Linux

  1. Open your Claude Desktop config file at:

    ~/.config/Claude/claude_desktop_config.json

  2. Add the MCP server configuration:

    Using the executable:

    {
  "mcpServers": {
    "time": {
      "command": "/absolute/path/to/mcp-time-server-linux"
    }
  }
}

    Using Python:

    {
  "mcpServers": {
    "time": {
      "command": "/usr/bin/python3",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

  3. Restart Claude Desktop completely (quit and reopen)

Building Executables

Prerequisites

pip install pyinstaller

Build for Current Platform

Run the build script:

python build.py

This will create a standalone executable in the dist/ directory.

Cross-Platform Building

Automated Builds (GitHub Actions)

This repository includes a GitHub Actions workflow that automatically builds executables for all platforms:

  • Builds on every push to main branch
  • Creates releases when you push a version tag (e.g., v1.0.0)
  • Builds for: Windows (x86_64), macOS (ARM64), Linux (x86_64)

To create a new release:

git tag v1.0.0
git push origin v1.0.0

The workflow will automatically build and attach executables to the GitHub release.

Manual Cross-Platform Building

PyInstaller creates executables for the platform you're building on:

  1. macOS executable: Build on macOS
  2. Linux executable: Build on Linux (or use Docker with a Linux image)
  3. Windows executable: Build on Windows (or use a Windows VM)

Usage Examples

Get Current Time

# Local time
get_current_time()

# Specific timezone
get_current_time(tz="America/New_York")
get_current_time(tz="Europe/London")
get_current_time(tz="Asia/Tokyo")

Parse and Validate Dates

# Parse a date
parse_datetime(
    date_string="2025-11-21 14:30:00",
    format_string="%Y-%m-%d %H:%M:%S"
)

# Validate a date
is_valid_datetime(
    date_string="2025-11-21",
    format_string="%Y-%m-%d"
)

Compare Times

compare_times(
    time1="2025-01-01 00:00:00",
    time2="2025-12-31 23:59:59",
    format_string="%Y-%m-%d %H:%M:%S"
)

Add/Subtract Time

# Add 5 days and 3 hours
add_time_delta(
    base_time="2025-11-21 10:00:00",
    days=5,
    hours=3,
    format_string="%Y-%m-%d %H:%M:%S"
)

# Subtract 2 days (use negative values)
add_time_delta(
    base_time="2025-11-21 10:00:00",
    days=-2,
    format_string="%Y-%m-%d %H:%M:%S"
)

Working with Timezones

# List all timezones
list_timezones()

# Filter timezones
list_timezones(filter_text="America")

# Get timezone info
get_timezone_info(tz="America/New_York")

Unix Timestamps

# Convert Unix timestamp to datetime
unix_to_datetime(timestamp=1732204800)

# With specific timezone
unix_to_datetime(timestamp=1732204800, tz="UTC")

Common DateTime Format Strings

FormatExample
%Y-%m-%d %H:%M:%S2025-11-21 14:30:00
%Y-%m-%d2025-11-21
%m/%d/%Y11/21/2025
%d/%m/%Y %H:%M21/11/2025 14:30
%B %d, %YNovember 21, 2025
%Y-%m-%dT%H:%M:%S2025-11-21T14:30:00 (ISO format)

Technical Details

Dependencies

  • Runtime: Python 3.10+
  • MCP Framework: mcp (FastMCP)
  • Build Tool: PyInstaller 6.0+
  • Timezone Data: tzdata (automatically included on Windows)

Standard Library Modules Used

  • datetime - Core date/time operations
  • zoneinfo - Timezone support (Python 3.9+)
  • time - Time utilities
  • typing - Type hints

Timezone Support

The server uses Python's zoneinfo module which:

  • On Unix systems (macOS/Linux): Uses system timezone database
  • On Windows: Requires tzdata package (automatically installed via dependencies)

Platform-Specific Notes

macOS

  • Timezone data from system (/usr/share/zoneinfo)
  • Executable will be for your Mac's architecture (Intel or Apple Silicon)

Linux

  • Timezone data from system (/usr/share/zoneinfo)
  • Build on the architecture you want to target (x86_64, ARM, etc.)

Windows

  • Requires tzdata package (included in dependencies)
  • May need to run build script as administrator
  • Antivirus might flag PyInstaller executables (false positive)

Troubleshooting

Windows: MCP Server Not Connecting to Claude Desktop

  1. Check the path: Make sure you're using double backslashes (\\) in the JSON config:

    "command": "C:\\Users\\YourName\\mcp-servers\\mcp-time-server-windows.exe"

  2. Check Windows Security: Windows Defender or antivirus may block the executable:

    • Right-click the .exe file → Properties → Check "Unblock" at the bottom → Apply
    • Or add an exception in Windows Security for the executable

  3. Verify the file path: Make sure the path in your config exactly matches where you saved the .exe file

  4. Check Claude Desktop logs: Look for error messages in the Claude Desktop logs to diagnose issues

Windows: Security Warning When Running Executable

Windows may show "Windows protected your PC" warning because the executable is unsigned:

  1. Click "More info"
  2. Click "Run anyway"
  3. This is safe - the executable is built from open source code via GitHub Actions

macOS: "Cannot be opened because the developer cannot be verified"

macOS Gatekeeper blocks unsigned executables by default:

  1. Method 1: Privacy & Security Settings (Recommended)

    • Try to run the executable (or start Claude Desktop with the server configured)
    • Open System Settings → Privacy & Security
    • Scroll down and click "Allow Anyway" next to the blocked app message
    • Try running again and click "Open" when prompted

  2. Method 2: Command Line

    xattr -d com.apple.quarantine ~/path/to/mcp-time-server-macos

  3. This is safe - the executable is built from open source code via GitHub Actions

"No timezone data found"

On Windows when running from source, ensure tzdata is installed:

pip install tzdata

This is not needed for the pre-built executable (tzdata is bundled).

Executable is too large

The executable includes Python runtime and all dependencies. Typical sizes:

  • macOS: 40-45 MB
  • Linux: 35-40 MB
  • Windows: 40-45 MB

To reduce size when building locally, you can disable UPX compression in the .spec file.

"Permission denied" when running executable

On Unix systems:

chmod +x mcp-time-server-macos  # or mcp-time-server-linux

License

MIT

Contributing

This is a simple, focused MCP server. If you need additional time utilities, feel free to fork and extend!