# passage-of-time-mcp gives a language model a calculator for time and a sense of context

> This Model Context Protocol server exposes a small set of time tools to an assistant: the current date and time in a timezone, the duration between two timestamps, whether a moment was a weekend or business hours, and helpers for parsing and formatting. It is a single Python file, it speaks the deprecated SSE transport, and the README says plainly that it keeps no memory.

**jlumbroso/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.

- Repository: https://github.com/jlumbroso/passage-of-time-mcp
- Stars: 721 · Forks: 50
- Language: Python
- License: MPL-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/jlumbroso-passage-of-time-mcp

## The premise: models cannot reliably do the arithmetic themselves

The repository starts from a philosophical question, whether AI can perceive the passage of time, and turns it into a practical problem. The README's framing is that LLMs cannot reliably calculate time differences, and that instead of publishing a paper about how bad these models are at mental arithmetic, the authors equipped them with a calculator for time.

That framing matters for how you read the tool list. These are not tools for a human. A human can work out that a meeting ran from 14:00 to 17:30 without a service. A language model asked the same question will produce a plausible answer, and the plausible answer is frequently wrong, which is the worst combination in an assistant.

The server is a Model Context Protocol server, so the tools are exposed to any MCP-compatible client, and the README names Claude.ai and Continue.dev as examples. The repository is Python, the licence is MPL-2.0, and the whole implementation is a single file named passage_of_time_mcp.py alongside a Pipfile, a lock file and a tests directory.

The authors describe the design as emerging from human and LLM collaboration, with the tool suite shaped by asking Claude what it needed rather than by imposing an interface. The philosophical framing is the story; the deliverable is seven time tools and a transport.

## The core tools: now, the difference, and the context around it

The tool set is easiest to understand in three groups, starting with the three the README calls the core functions.

current_datetime takes a timezone and returns the current date and time, with a default of America/New_York, and its example return is a plain string such as 2024-01-15 14:30:45 EST. The README calls it the foundation of temporal awareness, and the example conversation shows the model calling it when a user asks what time it is.

time_difference takes two timestamps and an optional unit, defaulting to auto, and returns a structured result rather than a string:

```python
# Example response:
{
    "seconds": 11401,
    "formatted": "3 hours, 10 minutes, 1 second",
    "requested_unit": 3.17,  # if unit="hours"
    "is_negative": false
}
```

The requested_unit field is the interesting one, since it is a number rather than a formatted value, so a caller can read the elapsed time in the unit it asked for. The is_negative flag keeps the sign of the difference explicit instead of relying on word order.

timestamp_context is the tool with no equivalent outside the project. Given a timestamp it answers the kind of question a database would not: what time of day is it, what day of the week, is it a weekend, is it business hours, what activity usually happens then, and how does it relate to today.

```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"
}
```

That last field, typical_activity, is a heuristic with a value judgement baked in, and it is the field most likely to be wrong for you. The README's own example conversation shows the intended use, where a request for help at 11:45 PM on a weekday leads the model to note the hour and adjust its tone.

## Parsing, adding and formatting the numbers

The remaining four tools are plumbing that keeps the arithmetic honest.

parse_timestamp converts a timestamp into several representations at once, which is what makes it useful when a model has to compare a timestamp from one system with one from another:

```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"
}
```

time_since answers the question people actually ask, which is how long ago something happened, and it adds a coarse context label:

```python
# Example response:
{
    "seconds": 7200,
    "formatted": "2 hours ago",
    "context": "earlier today"
}
```

add_time takes a timestamp, a duration and a unit, and returns the shifted time in both machine and human form, with the human form being the useful part for a model that has to write a sentence rather than a value.

format_duration converts a number of seconds into text, and the style parameter selects the register:

```python
# style="full": "2 hours, 30 minutes, 15 seconds"
# style="compact": "2h 30m 15s"
# style="minimal": "2:30:15"
```

The existence of three styles is a small design signal about the audience. Full is for a sentence in prose, minimal is for a log line or a table cell, and compact sits between them. A tool that only produced one format would force the model to rewrite values, which is where formatting mistakes come from.

## Installing and running the server locally

The prerequisites are Python 3.12 or later, pipenv or pip, and an MCP-compatible client. Installation is a clone followed by a dependency install:

```bash
git clone https://github.com/jlumbroso/passage-of-time-mcp.git
cd passage-of-time-mcp
```

```bash
pipenv install
# or with pip:
pip install fastmcp pytz
```

The pip route names the two runtime dependencies directly, fastmcp for the server framework and pytz for the timezone handling.

Running it takes one of two commands:

```bash
pipenv run server
# or directly:
pipenv run python passage_of_time_mcp.py
```

The server then starts on http://0.0.0.0:8000/sse. Two details of that line are worth pausing on. The path is /sse, which is the endpoint an MCP client is configured with, and the bind address is 0.0.0.0 rather than localhost, so the port is reachable from other machines on the network. For a tool whose only inputs are timestamps, that is not a large attack surface, but it is a network listener you chose to open.

The repository also carries a Pipfile and a Pipfile.lock, so a pipenv based setup pins the dependency versions, and there is a tests directory, so the time logic is covered by tests rather than only by demonstration.

## Connecting a web client means exposing the server publicly

The Claude.ai instructions are four steps: go to Settings then Integrations in Claude.ai, click Add integration and select Custom, enter the server URL, and save and enable all the time-related tools.

The URL example in the README is an ngrok URL with the /sse path at the end, and the note under the steps spells out the consequence. For local development you will need to expose your server using ngrok or deploy it to a public URL.

So the deployment story is a tunnel or a public host, and that is the first thing to think about. A time server has no secrets and no state, which makes it a reasonable candidate for public exposure, but a tunnel means the local port is forwarded to the internet while it is open, and the server does not authenticate the requests it serves. The README's own limitation list notes that the server requires a public URL for web-based clients, and the roadmap lists Docker support and a browser extension for local development, both of which would make the local case easier.

The timeouts and the SSE path are also fixed by the current transport. The SSE transport is deprecated but currently most reliable, per the Known Issues section, and the roadmap has an item to migrate to the modern http-stream transport. Until that migration lands, a client that has dropped SSE support is a client this server cannot serve.

## Strict formats, one default timezone, and no memory

Two constraints shape how the tools behave.

The first is input format. All timestamps must use one of two forms, the full YYYY-MM-DD HH:MM:SS, for example 2024-01-15 14:30:45, or the date only YYYY-MM-DD, for example 2024-01-15. The README gives the reason directly: this strict formatting prevents ambiguity and ensures reliable calculations. A permissive parser that accepted a dozen shapes would put the interpretation burden back on the model, which is the problem the project exists to remove.

The second is the timezone. The server defaults to America/New_York and supports all standard timezone names, with UTC, US/Pacific, Europe/London and Asia/Tokyo given as examples. The default is a choice worth noticing, because a model calling current_datetime without arguments gets Eastern time regardless of where the user is. The timezone is a parameter, so passing one is a matter of habit rather than capability.

The third constraint is the absence of memory. The Known Issues section lists no persistent memory of past time calculations. Every call is stateless, which means a model cannot ask what it computed five minutes ago, and it also means the server cannot accumulate a picture of your working rhythm across a session. The roadmap has an item for configurable activity patterns per user, and one for calendar integration, which are the features that would start to fill that gap, and both are unchecked.

## Where passage-of-time-mcp is the wrong tool

The first wrong case is anything that needs to survive a restart. A reminder, a recurring meeting, a deadline that must fire while you are asleep, none of that is what this server does. It computes, and it does not store. The roadmap's calendar integration entry is the acknowledgement of that boundary.

The second wrong case is a deployment where you cannot open a public URL. The web client path needs a tunnel or a public host, and the deprecated SSE transport narrows the client set you can serve. If your environment forbids that, this server is not deployable as documented, and the roadmap items that would fix it are unchecked.

The third is a model that already has good time handling. Recent assistants are given system prompts with the current date, and some tool suites already include a time tool. Adding a second clock to an assistant that can already answer what time it is adds a network hop and a source of disagreement, and the disagreement is the interesting failure mode, because one of the two answers is right and the model does not know which.

The alternative approach for the same goal is a prompt with the current date and a deterministic calculation step inside your own code. Where the difference lies is in the second half. A prompt can tell a model the time and can even tell it to be careful, but it cannot make the arithmetic reliable, and the arithmetic is exactly what goes wrong in ways that read as confidence. This server removes the arithmetic from the model's hands entirely, and gives up a server in exchange, with its statelessness, its public URL requirement and its deprecated transport.

## Conclusion

Adopt passage-of-time-mcp if your assistant makes claims about when things happened or how long an activity took, and you want the arithmetic done by code rather than guessed. Do not adopt it for scheduling, reminders or anything that must survive a restart, because the server has no persistent memory of past calculations, and treat the network exposure as a real constraint rather than a detail. Before you connect it, read the Known Issues section, check whether the deprecated SSE transport is acceptable for your client, confirm the timestamp formats the tools accept, and note that the default timezone is America/New_York and the server binds http://0.0.0.0:8000/sse.

## FAQ

### What is passage-of-time-mcp?

It is a Python Model Context Protocol server that exposes time related tools to a language model, including current_datetime, time_difference, timestamp_context, time_since, parse_timestamp, add_time and format_duration, so the model does not have to do time arithmetic itself.

### How do I install and run the passage-of-time-mcp server?

Clone the repository, install the dependencies with pipenv install or pip install fastmcp pytz, then start it with pipenv run server or pipenv run python passage_of_time_mcp.py. The server listens on http://0.0.0.0:8000/sse, and the prerequisites are Python 3.12 or later and an MCP-compatible client.

### What does the timestamp_context tool return?

It gives human context about a timestamp, including the time of day, the day of the week, whether it is a weekend, whether it falls in business hours, a typical activity label, and the relative day. The activity label is a heuristic, and the example in the README shows it used so a model can adjust its tone to the hour.

### Does passage-of-time-mcp remember anything between calls?

No. The Known Issues section lists no persistent memory of past time calculations, so every tool call is stateless. The roadmap contains an unchecked item for configurable activity patterns per user and one for calendar integration, which are the features that would start to change that.

### Which timestamp formats does passage-of-time-mcp accept?

Two: the full YYYY-MM-DD HH:MM:SS format and the date only YYYY-MM-DD format. The README says the strict formatting prevents ambiguity and ensures reliable calculations, and the server defaults its timezone to America/New_York while accepting standard timezone names.

## Sources

- [Issues](https://github.com/jlumbroso/passage-of-time-mcp/issues)
- [jlumbroso/passage-of-time-mcp on GitHub](https://github.com/jlumbroso/passage-of-time-mcp)
- [License: MPL-2.0](https://github.com/jlumbroso/passage-of-time-mcp/blob/main/LICENSE)
- [README](https://github.com/jlumbroso/passage-of-time-mcp/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jlumbroso-passage-of-time-mcp