--- slug: "time-converter-mcp-server" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/okooo5km/time-mcp-server@main/README.md" repo: "https://github.com/okooo5km/time-mcp-server" source_file: "README.md" branch: "main" --- # Time MCP Server > A Model Context Protocol server that provides time-related capabilities. This server enables LLMs to access current time information and convert times between different timezones. This is a Swift implementation of a time MCP server using the MCP Swift SDK. ![Swift Platform](https://img.shields.io/badge/platform-macOS-lightgrey) ![License](https://img.shields.io/badge/license-MIT-blue) ## ✨ Features * **Current Time Queries**: Get the current time in any timezone * **Time Zone Conversions**: Convert time between different timezones * **Daylight Saving Time Information**: Check if a timezone is currently in DST * **Time Difference Calculation**: Get the time difference between timezones when converting ## Available Tools * `get_current_time` - Get the current time in a specific timezone * `timezone` (string, required): IANA timezone name (e.g., 'America/New_York', 'Europe/London'). If empty or not provided, the system timezone will be used. * `convert_time` - Convert time between timezones * `source_timezone` (string, required): Source IANA timezone name. If empty or not provided, the system timezone will be used. * `time` (string, required): Time to convert in 24-hour format (HH:MM) * `target_timezone` (string, required): Target IANA timezone name. If empty or not provided, the system timezone will be used. ## Installation ### Option 1: Download Pre-built Binary Download the latest pre-built binary for your platform from the [GitHub Releases](https://github.com/okooo5km/time-mcp-server/releases/latest) page: Download the binary for your platform from the [GitHub Releases](https://github.com/okooo5km/time-mcp-server/releases/latest) page and follow the installation instructions below.
macOS Installation #### macOS with Apple Silicon (M1/M2/M3): ```bash # Download the arm64 version curl -L https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-macos-arm64.zip -o time-mcp-server.zip unzip time-mcp-server.zip chmod +x time-mcp-server # Remove quarantine attribute to avoid security warnings xattr -d com.apple.quarantine time-mcp-server # Install to your local bin directory mkdir -p ~/.local/bin mv time-mcp-server ~/.local/bin/ rm time-mcp-server.zip ``` #### macOS with Intel Processor: ```bash # Download the x86_64 version curl -L https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-macos-x86_64.zip -o time-mcp-server.zip unzip time-mcp-server.zip chmod +x time-mcp-server # Remove quarantine attribute to avoid security warnings xattr -d com.apple.quarantine time-mcp-server # Install to your local bin directory mkdir -p ~/.local/bin mv time-mcp-server ~/.local/bin/ rm time-mcp-server.zip ``` #### macOS Universal Binary (works on both Apple Silicon and Intel): ```bash # Download the universal version curl -L https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-macos-universal.zip -o time-mcp-server.zip unzip time-mcp-server.zip chmod +x time-mcp-server # Remove quarantine attribute to avoid security warnings xattr -d com.apple.quarantine time-mcp-server # Install to your local bin directory mkdir -p ~/.local/bin mv time-mcp-server ~/.local/bin/ rm time-mcp-server.zip ```
Linux Installation #### Linux on x86_64 (most common): ```bash # Download the amd64 version curl -L https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-linux-amd64.tar.gz -o time-mcp-server.tar.gz tar -xzf time-mcp-server.tar.gz chmod +x time-mcp-server # Install to your local bin directory mkdir -p ~/.local/bin mv time-mcp-server ~/.local/bin/ rm time-mcp-server.tar.gz ``` #### Linux on ARM64 (e.g., Raspberry Pi 4, AWS Graviton): ```bash # Download the arm64 version curl -L https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-linux-arm64.tar.gz -o time-mcp-server.tar.gz tar -xzf time-mcp-server.tar.gz chmod +x time-mcp-server # Install to your local bin directory mkdir -p ~/.local/bin mv time-mcp-server ~/.local/bin/ rm time-mcp-server.tar.gz ```
Windows Installation #### Windows on x86_64 (most common): - Download the [Windows AMD64 version](https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-windows-amd64.zip) - Extract the ZIP file - Move the `time-mcp-server.exe` to a location in your PATH #### Windows on ARM64 (e.g., Windows on ARM devices): - Download the [Windows ARM64 version](https://github.com/okooo5km/time-mcp-server/releases/latest/download/time-mcp-server-windows-arm64.zip) - Extract the ZIP file - Move the `time-mcp-server.exe` to a location in your PATH
Make sure the installation directory is in your PATH: - **macOS/Linux**: Add `export PATH="$HOME/.local/bin:$PATH"` to your shell configuration file (`.bashrc`, `.zshrc`, etc.) - **Windows**: Add the directory to your system PATH through the System Properties > Environment Variables dialog ### Option 2: Build from Source 1. Clone the repository: ```bash git clone https://github.com/okooo5km/time-mcp-server.git cd time-mcp-server ``` 2. Build the project: **Using Make (recommended):** ```bash # Build for your current platform make # Or build for a specific platform make build-darwin-universal # macOS Universal Binary make build-darwin-arm64 # macOS Apple Silicon make build-darwin-amd64 # macOS Intel make build-linux-amd64 # Linux x86_64 make build-linux-arm64 # Linux ARM64 make build-windows-amd64 # Windows x86_64 # Or build for all platforms at once make build-all # Create distribution packages for all platforms make dist ``` The binaries will be placed in the `.build` directory. **Using Swift directly:** ```bash swift build -c release ``` 3. Install the binary: ```bash # Install to user directory (recommended, no sudo required) mkdir -p ~/.local/bin cp time-mcp-server ~/.local/bin/ ``` Make sure `~/.local/bin` is in your PATH by adding to your shell configuration file: ```bash echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc source ~/.zshrc # or source ~/.bashrc ``` ## Command Line Arguments The server supports the following command line arguments: * `-h, --help`: Display help information about the server, its usage, and available options * `-v, --version`: Display the version number of the time-mcp-server * `-t, --transport `: Transport type to use (default: "stdio") * `stdio`: Standard input/output mode for direct integration with LLMs * `sse`: Server-Sent Events mode for web-based connections * `-p, --port `: Port to use when running in SSE mode (default: 8080) * `-l, --local-timezone `: Override the automatically detected local timezone with a specific IANA timezone name Example usage: ```bash # Display help information time-mcp-server --help # Display version information time-mcp-server --version # Start server with default settings (stdio mode) time-mcp-server # Start server in SSE mode on the default port (8080) time-mcp-server --transport sse # Start server in SSE mode on a custom port time-mcp-server --transport sse --port 9090 # Start server with a specific local timezone time-mcp-server --local-timezone Europe/London ``` When running in SSE mode, the server will be accessible via HTTP on the specified port, allowing web-based clients to connect. In stdio mode (default), the server communicates through standard input/output, which is ideal for direct integration with LLM applications. ### Configure for Claude.app Add to your Claude settings: ```json "mcpServers": { "RealTime": { "command": "time-mcp-server", "args": ["-l", "Asia/Shanghai"] } } ``` ### Configure for Cursor Add the following configuration to your Cursor editor's Settings - mcp.json: ```json { "mcpServers": { "RealTime": { "command": "time-mcp-server", "args": ["-l", "Asia/Shanghai"] } } } ``` ### Configure for ChatWise Add the memory MCP server to your Chatwise Settings - Tools. ![chatwise-settings-tools](https://github.com/okooo5km/time-mcp-server/raw/HEAD/screenshots/chatwise.webp) ### Example System Prompt You can use the following system prompt to help Claude utilize the time-mcp-server effectively: ``` You have access to time-related tools through MCP. Use these to help users: - Get the current time in any timezone - Convert times between timezones - Calculate time differences between locations - Plan meetings across different timezones Use the following tools appropriately: - `get_current_time` for checking the current time in a specific timezone - `convert_time` when the user needs to convert between timezones Always use proper IANA timezone names (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo') rather than abbreviations or common names. ``` ## Development Requirements * Swift 6.0 or later * macOS 14.0 or later * MCP Swift SDK 0.2.0 or later ## Usage Examples ### Getting Current Time ```json { "timezone": "America/New_York" } ``` Response: ```json { "timezone": "America/New_York", "datetime": "2024-11-05T14:30:45-05:00", "is_dst": false } ``` ### Converting Time ```json { "source_timezone": "America/Los_Angeles", "time": "15:30", "target_timezone": "Asia/Tokyo" } ``` Response: ```json { "source": { "timezone": "America/Los_Angeles", "datetime": "2024-11-05T15:30:00-08:00", "is_dst": false }, "target": { "timezone": "Asia/Tokyo", "datetime": "2024-11-06T08:30:00+09:00", "is_dst": false }, "time_difference": "+17h" } ``` ## Use Cases * **International Meeting Planning**: Schedule meetings across different timezones * **Travel Planning**: Check local times at destination * **Remote Work Coordination**: Coordinate work hours with international teams * **Event Scheduling**: Set up global events with correct local times * **Time-Sensitive Operations**: Ensure operations happen at the correct local time ## Version History See GitHub Releases for version history and changelog. ## ☕️ Support the Project If you find time-mcp-server helpful, please consider supporting its development: * ⭐️ Star the project on GitHub * 🐛 Report bugs or suggest features * 💝 Support via:

## License time-mcp-server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. ## About A Swift implementation of a time server for Model Context Protocol (MCP), enabling AI assistants to access current time information and convert between timezones. This project is built using the MCP Swift SDK.