This project provides a Model Context Protocol (MCP) server designed to equip Large Language Models (LLMs) with temporal awareness and time calculation capabilities. It addresses the LLM limitation of unreliable time difference calculations by offering a suite of tools for understanding and manipulating time, benefiting developers and researchers aiming to enhance LLM reasoning and contextual understanding.

How It Works

The server acts as a bridge, exposing a set of Python functions as tools that LLM clients can invoke. It leverages the fastmcp framework to manage these tool calls and responses. The core approach is to provide LLMs with explicit functions for obtaining current time, calculating time differences, contextualizing timestamps (e.g., weekends, business hours), and performing time arithmetic, thereby enabling more nuanced temporal reasoning.

Quick Start & Requirements

• Installation: git clone https://github.com/jlumbroso/passage-of-time-mcp.git followed by pipenv install or pip install fastmcp pytz.
• Running: pipenv run server or pipenv run python passage_of_time_mcp.py.
• Prerequisites: Python 3.12+, pipenv (or pip), and an MCP-compatible client (e.g., Claude.ai, Continue.dev). For web clients, a public URL via ngrok or deployment is required.
• Setup: Local setup involves cloning, installing dependencies, and running the server. Exposing the server via ngrok is necessary for external client connections.
• Documentation: Medium Article, MCP Documentation

Highlighted Details

• Offers tools for current_datetime, time_difference, timestamp_context, time_since, parse_timestamp, add_time, and format_duration.
• Designed through collaborative "human-LLM" interaction, focusing on practical needs.
• Emphasizes "Cognitive Partnership" and "Human Context Matters" in its design philosophy.
• Supports various timezone configurations and strict timestamp formats for reliability.

Maintenance & Community

The project is primarily maintained by Jérémie Lumbroso and was developed in collaboration with Claude Opus 4.0. It is inspired by research from Princeton University's Natural and Artificial Minds initiative.

Licensing & Compatibility

Licensed under the Mozilla Public License 2.0 (MPL 2.0). This license allows for open distribution and modification, with requirements for source code availability for modifications. It is generally compatible with commercial and closed-source applications, provided the MPL 2.0 terms are followed.

Limitations & Caveats

The project currently uses the deprecated SSE transport for communication, with plans to migrate to a modern HTTP-stream transport. There is no persistent memory of past time calculations, and natural language time parsing is a future feature. Docker support is also planned for future releases.