elimS2/mcp-time-server

MCP Time Server

A simple Model Context Protocol (MCP) server that provides current UTC time functionality. This server can be integrated globally with Cursor IDE to provide time-related capabilities across all projects.

Features

• Get current UTC time in multiple formats
• Simple MCP protocol implementation
• Global Cursor IDE integration
• Lightweight and fast

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Install from source

1. Clone or download this repository
2. Navigate to the project directory
3. Install the package:

pip install -e .

Install dependencies only

pip install -r requirements.txt

Usage

Running the server

# Run directly
python -m mcp_time_server.server

# Or use the installed script
mcp-time-server

Available Tools

get_current_time_utc

Get the current UTC time in various formats.

Parameters:

• format (optional): Output format
  • "iso" (default): ISO 8601 format (2025-01-15T10:30:45Z)
  • "datetime": Human-readable format (2025-01-15 10:30:45)
  • "timestamp": Unix timestamp (1736939445)

Example response:

Current UTC time: 2025-01-15T10:30:45.123456Z
Format: iso
Full ISO: 2025-01-15T10:30:45.123456Z

Cursor IDE Integration

Global Configuration (Recommended)

For permanent integration across all projects:

1. Create the global MCP configuration file:

   • Windows: C:\Users\[USERNAME]\.cursor\mcp.json
   • macOS/Linux: ~/.cursor/mcp.json

2. Add the following configuration:

{
  "mcpServers": {
    "time-server": {
      "command": "python",
      "args": ["-m", "mcp_time_server.server"],
      "cwd": "/full/path/to/mcp-time-server/src",
      "env": {
        "PYTHONPATH": "/full/path/to/mcp-time-server/src"
      }
    }
  }
}

3. Restart Cursor IDE
4. Check Tools & Integrations > MCP to verify the server is enabled

The server will now automatically start with Cursor IDE and work across all projects!

Project-Specific Configuration

For project-only usage, create .cursor/mcp.json in your project directory with the same structure.

Development

Development Setup

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
isort src/

# Type checking
mypy src/

Project Structure

mcp-time-server/
├── src/
│   └── mcp_time_server/
│       ├── __init__.py
│       └── server.py
├── pyproject.toml
├── requirements.txt
├── README.md
├── mcp_config.json
└── PROJECT_PLAN.md

Testing

Test the server functionality:

from mcp_time_server.server import get_current_time_utc

# Test different formats
print(get_current_time_utc("iso"))
print(get_current_time_utc("datetime"))
print(get_current_time_utc("timestamp"))

Troubleshooting

Common Issues

1. Import errors: Make sure the package is installed with pip install -e .
2. MCP connection issues: Verify the server path in your MCP configuration
3. Permission errors: Ensure Python has necessary permissions to run the server
4. Server not appearing: Check that the .cursor directory exists and mcp.json is properly formatted

Windows PowerShell

If you encounter issues with && operator in PowerShell, use:

cd src; python -m mcp_time_server.server

Verifying Server Status

Check if server is running:

# Windows
tasklist | findstr python
wmic process where "name='python.exe'" get ProcessId,CommandLine /format:list

# macOS/Linux  
ps aux | grep mcp_time_server

Test connection in Cursor: Ask the AI assistant to get current time - it should use the MCP Time Server automatically.

Manual Server Management

Start server manually:

cd src && python -m mcp_time_server.server

Stop server:

# Windows (replace PID with actual process ID)
taskkill /PID [PID] /F

License

MIT License - see LICENSE file for details.

Contributing

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

Changelog

v0.1.0

• Initial release
• Basic UTC time functionality
• MCP protocol compliance
• FastMCP integration for simplified server management
• Global Cursor IDE configuration support
• Multiple time formats (ISO, datetime, timestamp)
• Comprehensive testing and documentation
• Process management and troubleshooting tools
• GitHub repository with MIT license
• Live testing confirmed across restart cycles