Temporal Awareness

A Model Context Protocol (MCP) server that provides AI agents with comprehensive temporal awareness and time calculation capabilities.

python

3

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "pmbstyle-temporal-awareness-mcp": {
      "command": "poetry",
      "args": [
        "run",
        "python",
        "-m",
        "temporal_awareness_mcp.stdio_main"
      ]
    }
  }
}

You can equip AI agents with precise temporal awareness using this MCP server. It provides current time in any timezone, time calculations, time adjustments, and human-friendly timestamp context, all accessible through a controllable MCP interface. You can run it locally for development with stdio transport or deploy it for remote HTTP access in cloud environments.

How to use

To use this MCP server, start the local stdio instance and connect your MCP client to the stdio transport. This setup is ideal for development and testing on your machine. You can also deploy a server instance and expose an HTTP interface for remote clients.

How to install

# Clone the project
git clone https://github.com/pmbstyle/temporal-awareness-mcp.git
cd temporal-awareness-mcp

# Install dependencies (uses Poetry)
poetry install

# Run the server with stdio transport (local development)
poetry run python -m temporal_awareness_mcp.stdio_main

Additional sections

Configuration and deployment options are provided to support local development and cloud deployment. You can run a Docker-based deployment or start an HTTP server for remote clients. The server exposes a set of time-related tools that you can invoke via MCP.

Tools and usage

The server offers the following tools to work with time data. Use these endpoints in your MCP client to perform common temporal tasks.

Available tools and endpoints

get_current_time — Get the current date and time in a specified timezone. Parameters: timezone (string, optional, default "UTC"), format (string, optional, default "iso"). Example: determine the current time in Tokyo and format it as ISO.

Testing the server

Try these example prompts with your AI agent to validate functionality: basic time queries, date calculations, and complex scenarios that combine time zones and durations.

Development

Prerequisites: Python 3.12+, Poetry for dependency management, Docker is optional for containerized deployments.

Deployment

Docker deployment - Build and run the containerized server for cloud-style usage. HTTP deployment - Run the HTTP server to accept remote requests. The exact commands for starting the stdio and HTTP servers are shown in the installation steps above.

Environment and tools

The server supports both stdio and HTTP transports. Environment variables are not required for basic operation in the provided setup, but you can configure deployment environments as needed for production.

Notes

If you plan to expose the server publicly, consider securing access and restricting usage to trusted clients. For cloud deployments, Docker-based workflows can help you reproduce environments consistently.

Available tools

get_current_time

Return the current date and time for a specified timezone, with output formats such as ISO, human-friendly, or a timestamp.

calculate_difference

Compute the duration between two timestamps in a chosen unit (seconds, minutes, hours, or days).

get_timestamp_context

Provide human-friendly context about a timestamp in a given timezone.

adjust_timestamp

Add or subtract a duration from a base timestamp in a specified timezone.