passage-of-time-mcp
🤖🕰️ An MCP server that gives language models temporal awareness and time calculation abilities. Teaching AI the significance of the passage of time through collaborative tool development.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jlumbroso--passage-of-time-mcp)HTML
<a href="/listings/jlumbroso--passage-of-time-mcp"><img src="/api/listings/jlumbroso--passage-of-time-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
- Python 3.12+ - pipenv (or pip) - An MCP-compatible client (Claude.ai, Continue.dev, etc.)
Installation
1. Clone the repository:
git clone https://github.com/jlumbroso/passage-of-time-mcp.git cd passage-of-time-mcp
2. Install dependencies:
pipenv install # or with pip: pip install fastmcp pytz
3. Run the server:
pipenv run server # or directly: pipenv run python passage_of_time_mcp.py
The server will start on `http://0.0.0.0:8000/sse`.
Connecting to Claude.ai
1. In Claude.ai, go to Settings → Integrations 2. Click "Add integration" and select "Custom" 3. Enter the server URL (e.g., `https://your-server.ngrok-free.app/sse` if using ngrok, make sure to add `/sse` at the end) 4. Save and enable all the time-related tools
> **Note**: For local development, you'll need to expose your server using ngrok or deploy it to a public URL.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 319 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # "Passage of Time" Model Context Protocol (MCP) Server 🕐
- An MCP server that gives language models temporal awareness and time calculation abilities. Teaching LLMs the significance of the passage of time through collaborative tool development.
- 
- ## 📖 The Story
- This project emerged from a philosophical question: "Can AI perceive the passage of time?" What started as an exploration of machine consciousness became a practical solution to a real problem - LLMs can't reliably calculate time differences.
- Instead of publishing a paper about how "silly" these models are at mental math, we decided to do what we've done for ourselves: **equip them with a calculator for time**.
- Through human-LLM collaboration, we discovered that with proper temporal tools, models can uncover surprising insights about conversation patterns, work rhythms, and the human experience of time.
- [Read the full story on Medium →](https://medium.com/@jeremie.lumbroso/teaching-ai-the-significance-of-the-passage-of-time-yes-that-one-106ad7d20957)
- ## 🚀 Quick Start
- ### Prerequisites
- - Python 3.12+
- - pipenv (or pip)
- - An MCP-compatible client (Claude.ai, Continue.dev, etc.)
- ### Installation
- 1. Clone the repository:
- ```bash
- git clone https://github.com/jlumbroso/passage-of-time-mcp.git
- cd passage-of-time-mcp
- ```
- 2. Install dependencies:
- ```bash
- pipenv install
- # or with pip:
- pip install fastmcp pytz
- ```
- 3. Run the server:
- ```bash
- pipenv run server
- # or directly:
- pipenv run python passage_of_time_mcp.py
- ```
- The server will start on `http://0.0.0.0:8000/sse`.
- ### Connecting to Claude.ai
- 1. In Claude.ai, go to Settings → Integrations
- 2. Click "Add integration" and select "Custom"
- 3. Enter the server URL (e.g., `https://your-server.ngrok-free.app/sse` if using ngrok, make sure to add `/sse` at the end)
- 4. Save and enable all the time-related tools
- > **Note**: For local development, you'll need to expose your server using ngrok or deploy it to a public URL.
- ## 🛠️ Available Tools
- ### Core Functions
- #### `current_datetime(timezone="America/New_York")`
- Returns the current date and time. The foundation of temporal awareness.
- ```
- Returns: "2024-01-15 14:30:45 EST"
- ```
- #### `time_difference(timestamp1, timestamp2, unit="auto")`
- Calculates the duration between two timestamps with human-readable output.
- ```python
- # Example response:
- {
- "seconds": 11401,
- "formatted": "3 hours, 10 minutes, 1 second",
- "requested_unit": 3.17, # if unit="hours"
- "is_negative": false
- }
- ```
- #### `timestamp_context(timestamp)`
- Provides human context about a timestamp - is it weekend? Business hours? Dinner time?
- ```python
- # Example response:
- {
- "time_of_day": "evening",
- "day_of_week": "Saturday",
- "is_weekend": true,
- "is_business_hours": false,
- "typical_activity": "leisure_time",
- "relative_day": "today"
- }
- ```
- #### `time_since(timestamp)`
- Calculates how long ago something happened with contextual descriptions.
- ```python
- # Example response:
- {
- "seconds": 7200,
- "formatted": "2 hours ago",
- "context": "earlier today"
- }
- ```
- #### `parse_timestamp(timestamp)`
- Converts timestamps between different formats for maximum compatibility.
- ```python
- # Example response:
- {
- "iso": "2024-01-15T14:30:45-05:00",
- "unix": "1705343445",
- "human": "January 15, 2024 at 2:30 PM EST",
- "day_of_week": "Monday"
- }
- ```
- #### `add_time(timestamp, duration, unit)`
- Adds or subtracts time with natural language descriptions.
- ```python
- # Example response:
- {
- "result": "2024-01-16 14:30:45",
- "iso": "2024-01-16T14:30:45-05:00",
- "description": "tomorrow at 2:30 PM"
- }
- ```
- #### `format_duration(seconds, style="full")`
- Formats durations in various styles for different contexts.
- ```python
- # style="full": "2 hours, 30 minutes, 15 seconds"
- # style="compact": "2h 30m 15s"
- # style="minimal": "2:30:15"
- ```
- ## 💡 Example Conversations
- ### Basic Time Awareness
- ```
- Human: What time is it?
- Claude: [calls current_datetime] It's currently 3:45 PM EST on Monday, January 15, 2024.
- ```
- ### Conversation Rhythm Analysis
- ```
- Human: Let's have a discussion about AI consciousness.
- Claude: [calls current_datetime at start of each response]
- [After several exchanges]
- Human: What patterns do you notice in our conversation?
- Claude: Looking at the timestamps, I notice you're taking 30 seconds to 2 minutes between responses, suggesting active engagement. The 3-minute pause before your question about implementation shows deeper consideration...
- ```
- ### Understanding Work Context
- ```
- Human: [at 11:45 PM] Can you help me debug this code?
- Claude: [calls current_datetime, then timestamp_context]
- I see it's late night on a weekday. Given that it's approaching midnight, let me help you efficiently so you can get some rest. Here's a focused debugging approach...
- ```
- ## 🏗️ Design Philosophy
- This server embodies several key principles:
- 1. **Cognitive Partnership**: We treat LLMs as cognitive partners who need proper tools, not black boxes to be dressed up.
- 2. **Collaborative Design**: The tool suite emerged from asking Claude what they needed, not imposing our assumptions.
- 3. **Human Context Matters**: Time isn't just numbers - it's about understanding human rhythms, work patterns, and social contexts.
- 4. **Practical Over Perfect**: We provide the tools models actually need, tested through real conversations.
- ## 🔧 Configuration
- ### Timezone Support
- The server defaults to `America/New_York` but supports all standard timezone names:
- - `UTC`
- - `US/Pacific`
- - `Europe/London`
- - `Asia/Tokyo`
- - etc.
- ### Timestamp Formats
- All timestamps must use one of these formats:
- - Full: `YYYY-MM-DD HH:MM:SS` (e.g., "2024-01-15 14:30:45")
- - Date only: `YYYY-MM-DD` (e.g., "2024-01-15")
- This strict formatting prevents ambiguity and ensures reliable calculations.
- ## 🚧 Known Issues & Future Work
- ### Current Limitations
- - The SSE transport is deprecated but currently most reliable
- - Server requires public URL for web-based clients
- - No persistent memory of past time calculations
- ### Roadmap
- - [ ] Migrate to modern `http-stream` transport
- - [ ] Add Docker support for easier deployment
- - [ ] Create browser extension for local development
- - [ ] Add configurable activity patterns per user
- - [ ] Support for calendar integration
- - [ ] Natural language time parsing ("next Tuesday", "in 3 hours")
- ## 🤝 Contributing
- This project emerged from human-LLM collaboration and welcomes more of the same! Whether you're contributing solo or with AI assistance, we value:
- 1. **Practical additions** - Tools that solve real temporal understanding problems
- 2. **Human context** - Features that help models understand how humans experience time
- 3. **Clear documentation** - Examples that show real-world usage
- ### Development Setup
- First, clone the repository:
- ```bash
- git clone https://github.com/jlumbroso/passage-of-time-mcp.git
- cd passage-of-time-mcp
- ```
- Then, install dependencies (I am using `pipenv` because it simultaneously creates a virtual environment and installs package, but any pip-compatible tool will work):
- ```bash
- # Install dev dependencies
- pipenv install --dev
- # Run tests
- pipenv run test
- # Run server
- pipenv run server
- ```
- This will start the server on `http://0.0.0.0:8000/sse` on your local computer. However, for web-based clients to connect to it, you will need to expose it to the internet using a service like [ngrok](https://ngrok.com/).
- Assuming you have ngrok installed, you can run `ngrok http 8000` to expose the server to the internet, and then use the provided URL in your MCP client. By default, ngrok will provide the endpoint to use in the form of `https://<random-subdomain>.ngrok-free.app/` in the Terminal:
- ```bash
- ❤️ ngrok? We're hiring https://ngrok.com/careers
- Session Status online
- Account Jérémie Lumbroso (Plan: Free)
- Update update available (version 3.23.1, Ctrl-U to update)
- Version 3.22.1
- Region United States (us)
- Latency 31ms
- Latency 1575ms
- Web Interface http://127.0.0.1:4040
- Forwarding https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app ->
- Connections ttl opn rt1 rt5 p50 p90
- 1756 0 0.01 0.03 5.32 61.51
- HTTP Requests
- -------------
- 00:06:44.030 EDT POST /messages/ 202 Accepted
- 00:06:43.936 EDT POST /messages/ 202 Accepted
- 00:06:43.514 EDT GET /sse 200 OK
- 00:06:43.682 EDT POST /messages/ 202 Accepted
- 00:06:43.342 EDT POST /sse 405 Method Not Allowed
- ```
- In my case, I used `https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app`, but since we are using the "SSE" transport method, the endpoint will have `/sse` appended at the end, so the final URL will be `https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app/sse`.
- Once this endpoint exists, you can add the MCP server as an integration to LLMs, such as Claude, following these instructions:
- 
- Once you've connected the MCP server to Claude.ai, you should start receiving queries locally:
- ```bash
- $ pipenv run server
- /Users/jlumbroso/.asdf/installs/python/3.12.4/lib/python3.12/asyncio/events.py:88: DeprecationWarning: The run_sse_async method is deprecated (as of 2.3.2). Use run_http_async for a modern (non-SSE) alternative, or create an SSE app with `fastmcp.server.http.create_sse_app` and run it directly.
- self._context.run(self._callback, *self._args)
- [06/16/25 19:18:04] INFO Starting MCP server 'Passage of Time' with transport 'sse' on http://0.0.0.0:8000/sse server.py:1219
- INFO: Started server process [11373]
- INFO: Waiting for application startup.
- INFO: Application startup complete.
- INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
- INFO: 34.162.142.92:0 - "POST /sse HTTP/1.1" 405 Method Not Allowed
- INFO: 34.162.142.92:0 - "GET /sse HTTP/1.1" 200 OK
- INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
- INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
- INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
- INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
- INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
- INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
- ```
- Eventually, you will want to deploy this MCP server to a cloud provider such as Render.com, so your LLM doesn't have to contend with the unreliable nature of your local machine.
- ## 📝 License
- Mozilla Public License 2.0 - because good ideas should spread while staying open.
- ## 🙏 Acknowledgments
- - Created through extended collaboration between [Jérémie Lumbroso](https://github.com/jlumbroso) and Claude Opus 4.0 (Anthropic)
- - Inspired by the question: "Can AI perceive the passage of time?"
- - Built on [FastMCP](https://github.com/fastmcp/fastmcp) framework
- - Special thanks to the [Natural and Artificial Minds initiative](https://nam.ai.princeton.edu/) at Princeton University
- ## 📚 Further Reading
- - [Teaching AI "The Significance of the Passage of Time" - Medium Article](https://medium.com/@jeremie.lumbroso/teaching-ai-the-significance-of-the-passage-of-time-yes-that-one-106ad7d20957)
- - [We Can't Understand AI Using our Existing Vocabulary - Been Kim et al.](https://arxiv.org/abs/2502.07586)
- - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- ---
- *"We're not just building better LLM tools. We're teaching curious cognitive systems about what it means to be human—one timestamp at a time."*
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.