FastMCP DateTime Server

A comprehensive date and time MCP (Model Context Protocol) server built with FastMCP, providing timezone conversion, time calculations, and various datetime utilities.

Features

• Current Time: Get current time in any timezone or UTC
• Timezone Conversion: Convert times between different timezones
• Time Calculations: Calculate differences between times and add/subtract time intervals
• Timezone Information: Get detailed information about specific timezones
• Common Timezones: Access to a curated list of common timezones by region
• MCP Resources: Structured data access through MCP resources

Quick Start

Using Docker (Recommended)

1. Clone and build:

   git clone <repository-url>
   cd mcp-datetime
   docker-compose up --build

2. Or build manually:

   docker build -t datetime-mcp .
   docker run -p 8000:8000 datetime-mcp

Local Development

1. Install dependencies:

   pip install -r requirements.txt

2. Run the server:

   python server.py

The server will be available at http://localhost:8001

Available Tools

1. get_current_time

Get the current time in a specified timezone or UTC.

Parameters:

• timezone_name (optional): Timezone name (e.g., 'America/New_York', 'Europe/London')

Example:

# Get UTC time
result = await client.call_tool("get_current_time", {})

# Get time in specific timezone
result = await client.call_tool("get_current_time", {"timezone_name": "America/New_York"})

2. convert_timezone

Convert time from one timezone to another.

Parameters:

• time_str: Time string in format 'YYYY-MM-DD HH:MM:SS'
• from_timezone: Source timezone name
• to_timezone: Target timezone name

Example:

result = await client.call_tool("convert_timezone", {
    "time_str": "2024-01-15 14:30:00",
    "from_timezone": "America/New_York",
    "to_timezone": "Europe/London"
})

3. calculate_time_difference

Calculate the difference between two times.

Parameters:

• time1: First time string
• time2: Second time string
• timezone: Timezone for both times (default: UTC)

Example:

result = await client.call_tool("calculate_time_difference", {
    "time1": "2024-01-15 14:30:00",
    "time2": "2024-01-16 14:30:00",
    "timezone": "UTC"
})

4. get_timezone_info

Get detailed information about a specific timezone.

Parameters:

• timezone_name: Timezone name

Example:

result = await client.call_tool("get_timezone_info", {
    "timezone_name": "America/New_York"
})

5. list_common_timezones

Get a list of common timezones grouped by region.

Example:

result = await client.call_tool("list_common_timezones", {})

6. add_time

Add or subtract time from a given datetime.

Parameters:

• time_str: Base time string
• days: Number of days to add/subtract
• hours: Number of hours to add/subtract
• minutes: Number of minutes to add/subtract
• seconds: Number of seconds to add/subtract
• timezone: Timezone for the time (default: UTC)

Example:

result = await client.call_tool("add_time", {
    "time_str": "2024-01-15 14:30:00",
    "days": 1,
    "hours": 2,
    "timezone": "UTC"
})

Available Resources

1. data://timezones/common

Get a list of common timezones for easy reference.

2. data://time/current

Get the current UTC time as a resource.

3. data://time/format

Get information about supported time formats.

Supported Timezones

The server supports all timezones available in the pytz library, including:

• North America: America/New_York, America/Chicago, America/Denver, America/Los_Angeles
• Europe: Europe/London, Europe/Paris, Europe/Berlin, Europe/Rome
• Asia: Asia/Tokyo, Asia/Shanghai, Asia/Singapore, Asia/Dubai
• Australia: Australia/Sydney, Australia/Melbourne, Australia/Perth
• UTC: UTC

Time Format

All times should be provided in the format: YYYY-MM-DD HH:MM:SS

Example: 2024-01-15 14:30:00

Docker Configuration

Environment Variables

• PYTHONUNBUFFERED=1: Ensures Python output is not buffered
• PYTHONPATH=/app: Sets the Python path to the application directory

Ports

• 8001: HTTP API endpoint (mapped from container port 8000)

Health Check

The container includes a health check that verifies the server is responding on port 8000.

Development

Project Structure

mcp-datetime/
├── server.py          # Main FastMCP server
├── requirements.txt   # Python dependencies
├── Dockerfile        # Docker configuration
├── docker-compose.yml # Docker Compose configuration
└── README.md         # This file

Adding New Tools

To add a new tool, use the @mcp.tool decorator:

@mcp.tool
def my_new_tool(param1: str, param2: int) -> Dict[str, str]:
    """Description of what this tool does."""
    # Tool implementation
    return {"result": "success"}

Adding New Resources

To add a new resource, use the @mcp.resource decorator:

@mcp.resource("data://my/resource")
def my_resource() -> Dict[str, str]:
    """Description of this resource."""
    return {"data": "value"}

Testing

Using FastMCP Client

from fastmcp import Client

async def test_server():
    async with Client("http://localhost:8001") as client:
        # Test tools
        result = await client.call_tool("get_current_time", {})
        print(f"Current time: {result.data}")
        
        # Test resources
        timezones = await client.read_resource("data://timezones/common")
        print(f"Available timezones: {timezones}")

# Run the test
import asyncio
asyncio.run(test_server())

Using curl

# Test the server is running
curl http://localhost:8001/health

# Get current time
curl -X POST http://localhost:8001/tools/get_current_time \
  -H "Content-Type: application/json" \
  -d '{}'

Troubleshooting

Common Issues

1. Port already in use: Change the port in docker-compose.yml or stop other services using port 8000
2. Timezone errors: Ensure timezone names are valid (use list_common_timezones to see available options)
3. Time format errors: Ensure times are in YYYY-MM-DD HH:MM:SS format

Logs

# View Docker logs
docker-compose logs datetime-mcp

# Follow logs in real-time
docker-compose logs -f datetime-mcp

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the FastMCP documentation
3. Open an issue in the repository