# 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:
```bash
pip install -e .
```
### Install dependencies only
```bash
pip install -r requirements.txt
```
## Usage
### Running the server
```bash
# 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:
```json
{
"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
```bash
# 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:
```python
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:
```powershell
cd src; python -m mcp_time_server.server
```
### Verifying Server Status
**Check if server is running:**
```powershell
# 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:**
```bash
cd src && python -m mcp_time_server.server
```
**Stop server:**
```powershell
# 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
