temporal-awareness

Temporal Awareness MCP Server provides AI agents with robust time and date capabilities. It exposes tools to fetch the current time in a specified timezone, perform precise time calculations between timestamps, adjust timestamps by durations, and generate human-friendly context about given timestamps. The server supports both local stdio connections (for desktop workflows) and HTTP connections (for cloud or remote clients). You can run a stdio-based instance for development or a HTTP-based instance for remote usage and integration with clients that speak MCP over HTTP.

To use the tools, initialize the server (stdio or HTTP) and send MCP requests targeting the available tools: get_current_time, calculate_difference, get_timestamp_context, and adjust_timestamp. For example, you can request the current time in Tokyo with get_current_time and a format of iso or human, or compute how many days are left until a future date with calculate_difference. The server can also provide human-friendly context about a timestamp to help with interpretation. Use the HTTP transport if you need remote access, such as for cloud deployments or integration with web-based clients; use stdio for local development with Claude Desktop or Cursor IDE workflows.

Prerequisites

• Python 3.12+
• Poetry for dependency management (recommended)
• Docker (optional, for containerized deployment)

Install locally (development)

1. Clone the repository and install dependencies: git clone https://github.com/pmbstyle/temporal-awareness-mcp.git cd temporal-awareness-mcp poetry install

2. Run in stdio mode (local development): poetry run python -m temporal_awareness_mcp.stdio_main

Run in HTTP mode (remote/cloud):

1. Build and start with Docker (recommended for cloud deployments): docker-compose up -d --build

2. Or run directly with HTTP transport (local or remote): poetry run python -m temporal_awareness_mcp.http_main --host 0.0.0.0 --port 8000

Testing the server

• Ensure the server is running, then you can exercise the available tools via MCP clients or example prompts as described in the README under Testing and Development sections.

Notes and tips:

• The project supports two transports: stdio for local development and HTTP for remote usage. Choose the transport that fits your workflow.
• For production deployments, consider Docker (docker-compose) to simplify orchestration and scaling.
• The Environment Variables section mentions HOST and PORT for production; you can customize them via the mcp_config or environment when launching the HTTP server.
• If you encounter path or import issues when running from source, you may set PYTHONPATH to include the project src directory as described in the README alternatives.
• When integrating with clients (e.g., Claude Desktop, Cursor), ensure you configure the server_url and server_label to match the deployed HTTP endpoint and MCP server name.