Passage of Time MCP
Passage of Time MCP gives a model the current time and seven tools for intervals, shifts and date context, so it stops doing time arithmetic in its head
- 723 ★ on the repository
- Last commit
- MPL-2.0
Minimal access
Why this level
- Only reads the system clock and calculates dates, touching no files or external services
- Listens on port 8000 on all addresses with no token, and for web clients the author suggests exposing it through a tunnel
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/passage-of-time-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Only reads the system clock and calculates dates, touching no files or external services
- Listens on port 8000 on all addresses with no token, and for web clients the author suggests exposing it through a tunnel
This is third-party code. Review the repository files before installing.
What it does
Passage of Time MCP is a small MCP server in Python and FastMCP that covers a weak spot of language models: they do not know the current time and are poor at working out the gap between dates. The `current_datetime` tool returns the date and time in a chosen time zone, `America/New_York` by default. `time_difference` computes the interval between two stamps and returns seconds, a readable form and a negative flag, and `time_since` says how long ago an event was. `add_time` adds or subtracts a duration, `parse_timestamp` converts a stamp to ISO, Unix and human-readable forms, and `format_duration` renders seconds as a full, compact or minimal string. The `timestamp_context` tool describes a moment from a human point of view: time of day, day of the week, whether it is a weekend, whether it is business hours (in the code, Monday to Friday 9 to 17), a typical activity and a relative day such as today or yesterday. Stamps are accepted only as `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DD`, so parsing leaves no room for ambiguity. The server starts from a clone of the repository with `pipenv run server`. It listens on port 8000 (changed with the `PORT` variable) and serves MCP in two forms at once: streamable HTTP at `/mcp` and legacy SSE at `/sse`. A liveness check is available at `/health`. The server's instructions ask the model to call `current_datetime` at the start of every reply so it can feel the passage of time in a conversation.
Who it is for. For people who run an agent through long sessions and date-heavy tasks such as plans, deadlines, logs and term calculations, where the model needs the exact current time and reliable arithmetic.
Good fit when
- The agent must know today's date and hour in your time zone with no guessing from training data
- You need the span between two dates or the time since an event, and the result must be error-free via `time_difference` and `time_since`
- You need to shift a date by a given duration and get the answer in several formats with `add_time` and `parse_timestamp`
- The agent should consider time of day and weekends in its replies, for example not suggesting a call at midnight, and calls `timestamp_context` for that
- You want to trace the rhythm of a conversation from timestamps between messages
Not a fit when
- The machine has no Python 3.12: the version is stated in the prerequisites and in the Pipfile
- You need time zones outside what `pytz` supports or parsing of phrases like next Tuesday: the server accepts only the strict stamp format, and natural-language parsing is on the author's roadmap
- The server must be reachable by a web client without a public address: clients such as Claude.ai need an external URL, and a local run has to be exposed through a tunnel
- You need a calendar, reminders and events: calendar integration is only planned by the author
Example request
How much time has passed from 2026-03-01 09:00:00 until now, and what time will it be 45 minutes after that moment?MCP
- Transport
- http, sse
- Authentication
- not required
Environment variables
PORT- Server port, 8000 by default
Limitations
- The license is MPL-2.0.
- There is no PyPI package: the server is run from a clone through `pipenv`. The author lists Docker support and a browser extension in the plans, and there is no ready image in the repository.
- Web clients such as Claude.ai need a public address ending in `/sse`, and for a local run the author suggests `ngrok`. Clients that work with a local process can reach `localhost:8000`.
- The default time zone is `America/New_York` unless another is passed in each call. Business hours in `timestamp_context` are hard-coded: Monday to Friday, 9 to 17.
- The author calls SSE a deprecated transport and plans a move to streamable HTTP, although the code already serves both paths, `/mcp` and `/sse`. The server keeps no memory of earlier calculations.
How to disable. Stop the server process (Ctrl+C in the terminal running `pipenv run server`) and remove its address from the client's MCP settings. If the server was exposed through `ngrok`, close the tunnel. The clone folder can be deleted; the server creates no data of its own.
FAQ
Which tools does Passage of Time MCP provide?
Seven: `current_datetime`, `time_difference`, `time_since`, `parse_timestamp`, `add_time`, `timestamp_context` and `format_duration`. The first returns the current time and the rest compute intervals, shifts, formats and moment context.
What format should dates use?
Only `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DD`, for example `2024-01-15 14:30:00`. The author made the format strict to avoid ambiguity, and phrases like in three hours are not parsed.
How do I change the time zone?
Pass a `pytz` zone name in the `timezone` parameter, for example `UTC`, `Europe/London` or `Asia/Tokyo`. Without it `America/New_York` is used. The zone must be given in every call; there is no global setting.
Why do the server instructions ask for the time at the start of every reply?
By the author's design, repeated timestamps show the model how long the gaps between messages were. The repository examples rely on this: an analysis of conversation rhythm and the conclusion that it is late night when a user asks for debugging help at 23:45.
How do I connect the server to a web client?
In Claude.ai open Settings, the Integrations section, add a custom one and enter the address ending in `/sse`. For a local server the author suggests `ngrok http 8000` and pasting the issued address. This is the repository's description; menu item names in the client may change.
Are there tests and how do I run them?
Yes, the file `tests/test_passage_of_time_mcp.py`, run with `pipenv run test` after `pipenv install --dev`. Screenshots in the `docs` folder show the tools working in Claude.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for Weeek: projects, boards, tasks and time tracking with reports right from Claude Code
Minutes
minutes
A local-first MCP server for meeting memory: on-device recording and transcription into Markdown, searchable from Claude Code, Codex, Cursor and any MCP client
A recipe MCP server: the agent searches dishes by category, plans a weekly menu around allergies and suggests tonight's dinner
Kaiten MCP (Python)
Kaiten MCP
A single-file FastMCP server for Kaiten: 22 tools for cards, comments, checklists and time tracking
Weather API MCP Server: current weather by city
Weather API MCP Server
A weather MCP in Go: the current_weather tool gives the agent current weather by city name from WeatherAPI, run locally or in Docker
Plane MCP Server: project management in Plane
Plane MCP Server
Official Plane MCP server: the agent manages projects, work items, cycles and releases through 30 tools
README in short
The front page opens with the story of the project and a link to the author's article, then gives a quick start: cloning, installing dependencies and running the server. Next are a reference of the seven tools with sample responses, dialogues showing time awareness at work, design principles, time zone and format settings, known limitations and a roadmap. It ends with a contributor section covering tests and an `ngrok` walkthrough. The repository also holds tests, a `.replit` file and screenshots of the tools working in Claude.