Content
# Temporal Awareness MCP Server
A Model Context Protocol (MCP) server that provides AI agents with comprehensive temporal awareness and time calculation capabilities.
## Features
- **Current Time**: Get current date and time in any timezone
- **Time Calculations**: Calculate differences between timestamps
- **Time Adjustments**: Add or subtract durations from timestamps
- **Contextual Analysis**: Get human-readable context about timestamps
- **Multiple Transports**: Support for both stdio (local) and HTTP (remote) connections
- **Docker Support**: Ready for cloud deployment
## Quick Start
### For Local Development (Claude Desktop, Cursor)
1. **Install dependencies**:
```bash
git clone https://github.com/pmbstyle/temporal-awareness-mcp.git
cd temporal-awareness-mcp
poetry install
```
2. **Run with stdio transport**:
```bash
poetry run python -m temporal_awareness_mcp.stdio_main
```
### For Cloud Deployment
1. **Run with Docker**:
```bash
docker-compose up -d --build
```
2. **Or run directly with HTTP transport**:
```bash
poetry run python -m temporal_awareness_mcp.http_main --host 0.0.0.0 --port 8000
```
## Integration Guide
### Claude Desktop
Add to your Claude Desktop configuration file:
**For Windows:**
```json
{
"mcpServers": {
"temporal-awareness": {
"command": "cmd",
"args": ["/c", "cd /d \"C:\\path\\to\\temporal-awareness-mcp\" && poetry run python -m temporal_awareness_mcp.stdio_main"],
"env": {}
}
}
}
```
**For macOS/Linux:**
```json
{
"mcpServers": {
"temporal-awareness": {
"command": "sh",
"args": ["-c", "cd '/path/to/temporal-awareness-mcp' && poetry run python -m temporal_awareness_mcp.stdio_main"],
"env": {}
}
}
}
```
> **Important**: Replace `/path/to/temporal-awareness-mcp` with your actual project directory.
**Alternative: Using Python with PYTHONPATH**
If you prefer not to use Poetry:
```json
{
"mcpServers": {
"temporal-awareness": {
"command": "python",
"args": ["-m", "temporal_awareness_mcp.stdio_main"],
"env": {
"PYTHONPATH": "/path/to/temporal-awareness-mcp/src"
}
}
}
}
```
### Cursor IDE
Configure in Cursor Settings > Extensions > MCP:
```json
{
"servers": {
"temporal-awareness": {
"command": "poetry",
"args": ["run", "python", "-m", "temporal_awareness_mcp.stdio_main"],
"cwd": "/path/to/temporal-awareness-mcp"
}
}
}
```
### OpenAI and Cloud Clients
For cloud-based AI services, deploy the server and use HTTP transport:
1. **Deploy with ngrok (development)**:
```bash
# Terminal 1: Start the server
docker-compose up -d --build
# Terminal 2: Expose with ngrok
ngrok http 8000
```
2. **Use the public URL in your MCP client**:
```json
{
"type": "mcp",
"server_label": "temporal-awareness",
"server_url": "https://your-ngrok-url.ngrok.app/sse",
"require_approval": "never"
}
```
3. **Production deployment**: Deploy to Railway, Heroku, Google Cloud Run, etc.
## Available Tools
### `get_current_time`
Get the current date and time in a specified timezone.
**Parameters:**
- `timezone` (string, optional): Timezone name (default: "UTC")
- `format` (string, optional): Output format - "iso", "human", or "timestamp" (default: "iso")
**Example:**
```
What time is it in Tokyo?
```
### `calculate_difference`
Calculate the duration between two timestamps.
**Parameters:**
- `start_time` (string): Start timestamp (ISO format or human readable)
- `end_time` (string): End timestamp (ISO format or human readable)
- `unit` (string, optional): Result unit - "seconds", "minutes", "hours", or "days" (default: "seconds")
**Example:**
```
How long is it from 9:00 AM to 5:30 PM?
```
### `get_timestamp_context`
Provide human-readable context about a timestamp.
**Parameters:**
- `timestamp` (string): Timestamp to analyze
- `timezone` (string, optional): Timezone for context (default: "UTC")
**Example:**
```
Is March 15, 2024 2:30 PM a business day?
```
### `adjust_timestamp`
Add or subtract a duration from a timestamp.
**Parameters:**
- `timestamp` (string): Base timestamp
- `adjustment` (string): Adjustment to apply (e.g., "+1 day", "-2 hours")
- `timezone` (string, optional): Timezone for calculation (default: "UTC")
**Example:**
```
What date is 30 days after March 1, 2024?
```
## Testing the Server
Try these example prompts with your AI agent:
### Basic Operations
- "What time is it right now?"
- "What's the current time in Tokyo?"
- "Convert 3:30 PM EST to Pacific Time"
### Date Calculations
- "How many days until Christmas?"
- "What day of the week was January 1st, 2000?"
- "Add 45 days to March 15, 2024"
### Complex Scenarios
- "I have a flight departing Los Angeles at 11:30 PM on Friday. If the flight is 14 hours long, what time will I arrive in Tokyo local time?"
- "Calculate work hours in February 2024, assuming 8-hour workdays Monday through Friday"
## Development
### Prerequisites
- Python 3.12+
- Poetry for dependency management
- Docker (optional, for containerized deployment)
### Setup
```bash
# Clone and install
git clone <repository-url>
cd temporal-awareness-mcp
poetry install
# Run tests
poetry run pytest
```
## Deployment
### Docker
```bash
# Build and run
docker-compose up -d --build
# Check logs
docker-compose logs temporal-awareness-mcp-server
# Stop
docker-compose down
```
### Environment Variables
For production deployment, you can configure:
- `HOST`: Server host (default: "0.0.0.0")
- `PORT`: Server port (default: 8000)
## License
MIT License
