time-mcp-server

cwerder/time-mcp-server

3.1

If you are the rightful owner of time-mcp-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.

The Time MCP Server is a Model Context Protocol server that provides time and timezone functionalities for AI assistants, built using the FastMCP framework.

Tools
2
Resources
0
Prompts
0

Time MCP Server

A Model Context Protocol (MCP) server that provides time and timezone functionality for AI assistants. Built with FastMCP.

Features

  • Time Tools: Get current date/time in any timezone
  • Timezone Resource: Browse common global timezones with current times
  • Educational Prompt: Example prompt demonstrating MCP usage patterns
  • Math Utility: Simple addition function for demonstration

Prerequisites

  • Python 3.12+
  • uv package manager
  • Claude Desktop (for integration)

Installation

  1. Clone or download this repository
  2. Ensure uv is installed via Homebrew: 
    brew install uv

Usage

Command Line

Run the MCP server directly:

uv run --with fastmcp fastmcp run main.py

This will start the server and display connection information. The server uses STDIO transport for communication.

Claude Desktop Integration

To use this server with Claude Desktop:

  1. Install to Claude Desktop:

    fastmcp install claude-desktop main.py

  2. Restart Claude Desktop completely (quit and reopen)

  3. Verify connection: The server should appear as "My First MCP Server" in Claude Desktop's MCP servers list

Manual Configuration

Alternatively, manually add to your Claude Desktop config file at: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "My First MCP Server": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/Users/path/to/your/time-mcp-server/main.py"
      ],
      "env": {},
      "transport": "stdio"
    }
  }
}

Available Capabilities

Tools

  • add(a, b): Adds two integers together
  • get_current_datetime(timezone): Get current date/time in specified timezone
    • Default timezone: "America/New_York"
    • Supports all IANA timezone identifiers
    • Returns formatted date, time, datetime, and ISO format

Resources

  • timezones://common: List of major global timezones with current times
    • Includes 12 major business centers worldwide
    • Shows current time, date, and full datetime for each zone
    • Updates dynamically with real-time information

Prompts

  • business_hub_times: Educational example prompt
    • Demonstrates how to create reusable message templates
    • Guides AI assistants to use timezone resources
    • Returns: "Show me the current time in all major business hubs around the world"

Examples

Getting Time in Different Zones

Ask Claude Desktop:

  • "What time is it in Tokyo?"
  • "Show me the current time in London and New York"
  • "What's the time difference between San Francisco and Sydney?"

Using the Timezone Resource

Ask Claude Desktop:

  • "Show me all available timezones"
  • "What are the current times in major business centers?"

Using the Educational Prompt

The business_hub_times prompt can be invoked to demonstrate how prompts work in MCP systems.

Development

Project Structure

time-mcp-server/
�� main.py              # MCP server implementation
�� pyproject.toml       # Project configuration
�� uv.lock             # Dependency lock file
�� README.md           # This file

Key Components

  • FastMCP Framework: Handles MCP protocol communication
  • Timezone Handling: Uses Python's zoneinfo for accurate timezone data
  • Decorator Pattern: Tools, resources, and prompts defined with @mcp decorators

Testing the Server

  1. Command Line Test:

    uv run --with fastmcp fastmcp run main.py

    Should display server startup information and connection details.

  2. Claude Desktop Test: After integration, try asking Claude Desktop time-related questions to verify the tools are working.

Troubleshooting

Server Won't Start

  • Ensure uv is installed and in PATH: which uv
  • Check that the server file exists and is accessible
  • Verify Python 3.12+ is available: python --version

Claude Desktop Integration Issues

  • Check the logs at: ~/Library/Logs/Claude/mcp-server-My-First-MCP-Server.log
  • Ensure the full path to your main.py is correct in the config
  • Restart Claude Desktop after configuration changes
  • Verify uv is at /opt/homebrew/bin/uv (for Homebrew installation)

Common Issues

  • "spawn uv ENOENT": uv not found in PATH - use full path in config
  • Server disconnected: Check file paths and permissions
  • Import errors: Ensure FastMCP dependencies are available

Learn More