Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jlumbroso--passage-of-time-mcp/badge.svg)](/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

i

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)

  1. # "Passage of Time" Model Context Protocol (MCP) Server 🕐
  2. 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.
  3. ![Claude's Passage of Time Tools](docs/screenshot-0.png)
  4. ## 📖 The Story
  5. 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.
  6. 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**.
  7. 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.
  8. [Read the full story on Medium →](https://medium.com/@jeremie.lumbroso/teaching-ai-the-significance-of-the-passage-of-time-yes-that-one-106ad7d20957)
  9. ## 🚀 Quick Start
  10. ### Prerequisites
  11. - Python 3.12+
  12. - pipenv (or pip)
  13. - An MCP-compatible client (Claude.ai, Continue.dev, etc.)
  14. ### Installation
  15. 1. Clone the repository:
  16. ```bash
  17. git clone https://github.com/jlumbroso/passage-of-time-mcp.git
  18. cd passage-of-time-mcp
  19. ```
  20. 2. Install dependencies:
  21. ```bash
  22. pipenv install
  23. # or with pip:
  24. pip install fastmcp pytz
  25. ```
  26. 3. Run the server:
  27. ```bash
  28. pipenv run server
  29. # or directly:
  30. pipenv run python passage_of_time_mcp.py
  31. ```
  32. The server will start on `http://0.0.0.0:8000/sse`.
  33. ### Connecting to Claude.ai
  34. 1. In Claude.ai, go to Settings → Integrations
  35. 2. Click "Add integration" and select "Custom"
  36. 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)
  37. 4. Save and enable all the time-related tools
  38. > **Note**: For local development, you'll need to expose your server using ngrok or deploy it to a public URL.
  39. ## 🛠️ Available Tools
  40. ### Core Functions
  41. #### `current_datetime(timezone="America/New_York")`
  42. Returns the current date and time. The foundation of temporal awareness.
  43. ```
  44. Returns: "2024-01-15 14:30:45 EST"
  45. ```
  46. #### `time_difference(timestamp1, timestamp2, unit="auto")`
  47. Calculates the duration between two timestamps with human-readable output.
  48. ```python
  49. # Example response:
  50. {
  51. "seconds": 11401,
  52. "formatted": "3 hours, 10 minutes, 1 second",
  53. "requested_unit": 3.17, # if unit="hours"
  54. "is_negative": false
  55. }
  56. ```
  57. #### `timestamp_context(timestamp)`
  58. Provides human context about a timestamp - is it weekend? Business hours? Dinner time?
  59. ```python
  60. # Example response:
  61. {
  62. "time_of_day": "evening",
  63. "day_of_week": "Saturday",
  64. "is_weekend": true,
  65. "is_business_hours": false,
  66. "typical_activity": "leisure_time",
  67. "relative_day": "today"
  68. }
  69. ```
  70. #### `time_since(timestamp)`
  71. Calculates how long ago something happened with contextual descriptions.
  72. ```python
  73. # Example response:
  74. {
  75. "seconds": 7200,
  76. "formatted": "2 hours ago",
  77. "context": "earlier today"
  78. }
  79. ```
  80. #### `parse_timestamp(timestamp)`
  81. Converts timestamps between different formats for maximum compatibility.
  82. ```python
  83. # Example response:
  84. {
  85. "iso": "2024-01-15T14:30:45-05:00",
  86. "unix": "1705343445",
  87. "human": "January 15, 2024 at 2:30 PM EST",
  88. "day_of_week": "Monday"
  89. }
  90. ```
  91. #### `add_time(timestamp, duration, unit)`
  92. Adds or subtracts time with natural language descriptions.
  93. ```python
  94. # Example response:
  95. {
  96. "result": "2024-01-16 14:30:45",
  97. "iso": "2024-01-16T14:30:45-05:00",
  98. "description": "tomorrow at 2:30 PM"
  99. }
  100. ```
  101. #### `format_duration(seconds, style="full")`
  102. Formats durations in various styles for different contexts.
  103. ```python
  104. # style="full": "2 hours, 30 minutes, 15 seconds"
  105. # style="compact": "2h 30m 15s"
  106. # style="minimal": "2:30:15"
  107. ```
  108. ## 💡 Example Conversations
  109. ### Basic Time Awareness
  110. ```
  111. Human: What time is it?
  112. Claude: [calls current_datetime] It's currently 3:45 PM EST on Monday, January 15, 2024.
  113. ```
  114. ### Conversation Rhythm Analysis
  115. ```
  116. Human: Let's have a discussion about AI consciousness.
  117. Claude: [calls current_datetime at start of each response]
  118. [After several exchanges]
  119. Human: What patterns do you notice in our conversation?
  120. 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...
  121. ```
  122. ### Understanding Work Context
  123. ```
  124. Human: [at 11:45 PM] Can you help me debug this code?
  125. Claude: [calls current_datetime, then timestamp_context]
  126. 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...
  127. ```
  128. ## 🏗️ Design Philosophy
  129. This server embodies several key principles:
  130. 1. **Cognitive Partnership**: We treat LLMs as cognitive partners who need proper tools, not black boxes to be dressed up.
  131. 2. **Collaborative Design**: The tool suite emerged from asking Claude what they needed, not imposing our assumptions.
  132. 3. **Human Context Matters**: Time isn't just numbers - it's about understanding human rhythms, work patterns, and social contexts.
  133. 4. **Practical Over Perfect**: We provide the tools models actually need, tested through real conversations.
  134. ## 🔧 Configuration
  135. ### Timezone Support
  136. The server defaults to `America/New_York` but supports all standard timezone names:
  137. - `UTC`
  138. - `US/Pacific`
  139. - `Europe/London`
  140. - `Asia/Tokyo`
  141. - etc.
  142. ### Timestamp Formats
  143. All timestamps must use one of these formats:
  144. - Full: `YYYY-MM-DD HH:MM:SS` (e.g., "2024-01-15 14:30:45")
  145. - Date only: `YYYY-MM-DD` (e.g., "2024-01-15")
  146. This strict formatting prevents ambiguity and ensures reliable calculations.
  147. ## 🚧 Known Issues & Future Work
  148. ### Current Limitations
  149. - The SSE transport is deprecated but currently most reliable
  150. - Server requires public URL for web-based clients
  151. - No persistent memory of past time calculations
  152. ### Roadmap
  153. - [ ] Migrate to modern `http-stream` transport
  154. - [ ] Add Docker support for easier deployment
  155. - [ ] Create browser extension for local development
  156. - [ ] Add configurable activity patterns per user
  157. - [ ] Support for calendar integration
  158. - [ ] Natural language time parsing ("next Tuesday", "in 3 hours")
  159. ## 🤝 Contributing
  160. This project emerged from human-LLM collaboration and welcomes more of the same! Whether you're contributing solo or with AI assistance, we value:
  161. 1. **Practical additions** - Tools that solve real temporal understanding problems
  162. 2. **Human context** - Features that help models understand how humans experience time
  163. 3. **Clear documentation** - Examples that show real-world usage
  164. ### Development Setup
  165. First, clone the repository:
  166. ```bash
  167. git clone https://github.com/jlumbroso/passage-of-time-mcp.git
  168. cd passage-of-time-mcp
  169. ```
  170. Then, install dependencies (I am using `pipenv` because it simultaneously creates a virtual environment and installs package, but any pip-compatible tool will work):
  171. ```bash
  172. # Install dev dependencies
  173. pipenv install --dev
  174. # Run tests
  175. pipenv run test
  176. # Run server
  177. pipenv run server
  178. ```
  179. 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/).
  180. 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:
  181. ```bash
  182. ❤️ ngrok? We're hiring https://ngrok.com/careers
  183. Session Status online
  184. Account Jérémie Lumbroso (Plan: Free)
  185. Update update available (version 3.23.1, Ctrl-U to update)
  186. Version 3.22.1
  187. Region United States (us)
  188. Latency 31ms
  189. Latency 1575ms
  190. Web Interface http://127.0.0.1:4040
  191. Forwarding https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app ->
  192. Connections ttl opn rt1 rt5 p50 p90
  193. 1756 0 0.01 0.03 5.32 61.51
  194. HTTP Requests
  195. -------------
  196. 00:06:44.030 EDT POST /messages/ 202 Accepted
  197. 00:06:43.936 EDT POST /messages/ 202 Accepted
  198. 00:06:43.514 EDT GET /sse 200 OK
  199. 00:06:43.682 EDT POST /messages/ 202 Accepted
  200. 00:06:43.342 EDT POST /sse 405 Method Not Allowed
  201. ```
  202. 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`.
  203. Once this endpoint exists, you can add the MCP server as an integration to LLMs, such as Claude, following these instructions:
  204. ![Setting up the passage-of-time MCP server in Claude's interface - each tool comes with clear descriptions and permissions](docs/screenshot-5b.png)
  205. Once you've connected the MCP server to Claude.ai, you should start receiving queries locally:
  206. ```bash
  207. $ pipenv run server
  208. /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.
  209. self._context.run(self._callback, *self._args)
  210. [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
  211. INFO: Started server process [11373]
  212. INFO: Waiting for application startup.
  213. INFO: Application startup complete.
  214. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
  215. INFO: 34.162.142.92:0 - "POST /sse HTTP/1.1" 405 Method Not Allowed
  216. INFO: 34.162.142.92:0 - "GET /sse HTTP/1.1" 200 OK
  217. INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
  218. INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
  219. INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
  220. INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
  221. INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
  222. INFO: 34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 Accepted
  223. ```
  224. 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.
  225. ## 📝 License
  226. Mozilla Public License 2.0 - because good ideas should spread while staying open.
  227. ## 🙏 Acknowledgments
  228. - Created through extended collaboration between [Jérémie Lumbroso](https://github.com/jlumbroso) and Claude Opus 4.0 (Anthropic)
  229. - Inspired by the question: "Can AI perceive the passage of time?"
  230. - Built on [FastMCP](https://github.com/fastmcp/fastmcp) framework
  231. - Special thanks to the [Natural and Artificial Minds initiative](https://nam.ai.princeton.edu/) at Princeton University
  232. ## 📚 Further Reading
  233. - [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)
  234. - [We Can't Understand AI Using our Existing Vocabulary - Been Kim et al.](https://arxiv.org/abs/2502.07586)
  235. - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
  236. ---
  237. *"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 in

Free to use. If it’s helped, pass it on.