# Hermes Time MCP

> Give Hermes Agent real-world time awareness through the Model Context Protocol (MCP).

Hermes Time MCP is a lightweight MCP server that augments **Hermes Agent** with reliable, real-time date and time capabilities.

Hermes is an excellent autonomous AI agent, but like every Large Language Model, it has **no intrinsic awareness of the current time**. It cannot continuously observe the passing of time or consult a system clock on its own.

This project fills that capability gap by allowing Hermes to query an authoritative clock whenever temporal information is required, enabling it to behave more like a real digital assistant rather than a stateless language model.

---

# Motivation

A human assistant always knows:

- What time it is
- Today's date
- The current timezone
- How much time has passed
- What time it is somewhere else in the world

A language model knows none of these things unless external information is supplied.

Without an external time source, Hermes may:

- Produce stale timestamps
- Be unable to answer "What time is it?"
- Struggle with timezone calculations
- Have difficulty scheduling actions
- Lose temporal awareness during long-running conversations

Injecting timestamps into prompts is only a temporary solution. As conversations continue, those timestamps become stale.

The correct architectural approach is to allow Hermes to request time information only when it needs it.

That is exactly what the Model Context Protocol was designed to do.

---

# Purpose

Hermes Time MCP provides Hermes with an authoritative source of temporal information.

Whenever Hermes needs current time information, it simply invokes one of the MCP tools exposed by this server.

The server retrieves the information from the host operating system and returns the result to Hermes.

This keeps:

- Hermes focused on reasoning
- The operating system responsible for timekeeping
- The MCP server responsible for exposing time as a tool

Each component has a single responsibility.

---

# Design Philosophy

This project intentionally follows the Unix philosophy:

> Do one thing well.

Hermes performs reasoning.

The operating system maintains accurate time.

The MCP server bridges those two worlds.

The server **does not** synchronize clocks.

It **does not** contact NTP servers.

It **does not** maintain its own clock.

Instead, it trusts the operating system, which should already synchronize time using standard Linux services such as:

- Chrony
- systemd-timesyncd
- ntpd

This avoids unnecessary complexity while ensuring consistency with the rest of the system.

---

# Architecture

```text
                     User
                       │
                       ▼
               Hermes Agent
                       │
          MCP Streamable HTTP
                       │
                       ▼
                Hermes Time MCP
                  (mcp-proxy)
                       │
                    stdio MCP
                       │
                       ▼
             Python FastMCP Server
                       │
                 datetime/zoneinfo
                       │
                       ▼
             Host Operating System
                       │
               System Clock (UTC)
                       │
             Chrony / NTP / timesyncd
```

---

# Features

Current implementation includes:

- Current date
- Current local time
- Current UTC time
- ISO-8601 timestamps
- Timezone-aware date/time
- Timezone conversion utilities
- Fully MCP-compliant tool interface
- Docker deployment
- HTTP transport using `mcp-proxy`

The project is intentionally lightweight and designed to be extended with additional time-related tools.

---

# Repository Structure

```text
.
├── app/
│   ├── __init__.py
│   └── server.py
├── tests/
│   └── test_server.py
├── hermes/
│   └── config.yaml.example
├── Dockerfile
├── Dockerfile.test
├── docker-compose.yaml
├── Makefile
├── requirements.txt
├── requirements-dev.txt
└── README.md
```

---

# Requirements

- Docker
- Docker Compose
- Python 3.12 (development only)

---

# Running Tests

The project includes automated unit tests.

Build the test image:

```bash
docker build -f Dockerfile.test -t hermes-time-mcp:test .
```

Run the tests:

```bash
docker run --rm hermes-time-mcp:test
```

Expected output:

```text
.....
5 passed
```

Alternatively:

```bash
make test
```

---

# Building

Build the production container:

```bash
docker compose build
```

or

```bash
docker build -t hermes-time-mcp .
```

---

# Deployment

## Create the Docker network

```bash
docker network create time-net
```

Only required once.

---

## Configure Environment

Create a `.env` file.

```text
MCP_PORT=8815
DEFAULT_TIMEZONE=Europe/Oslo
```

---

## Start the Server

```bash
docker compose up -d
```

Verify:

```bash
docker compose ps
```

View logs:

```bash
docker logs time-mcp
```

---

# Hermes Configuration

Example Hermes configuration:

```yaml
mcp_servers:
  Hermes_clock:
    url: http://time-mcp:8815/mcp
    enabled: true
```

Reload MCP servers:

```text
/reload-mcp
```

---

# Verifying Connectivity

From the Docker host:

```bash
curl http://localhost:8815/mcp
```

A browser or curl request may return an HTTP 400 or 405 response.

This is expected.

MCP endpoints are designed for MCP clients, not web browsers.

The important point is that the endpoint is reachable.

---

# Example Usage

Ask Hermes:

> What time is it right now?

Hermes automatically calls the Time MCP server.

Ask:

> What time is it in Tokyo?

Hermes retrieves the current time and timezone information.

Ask:

> Generate an RFC3339 timestamp.

Hermes requests the timestamp from the MCP server instead of attempting to invent one.

---

# Security

The server is intentionally simple.

Recommendations:

- Run as a non-root user where practical
- Drop unnecessary Linux capabilities
- Use read-only containers where appropriate
- Never expose the Docker socket to the container
- Let the operating system manage clock synchronization

The server itself never attempts to modify system time.

---

# Why MCP Instead of Prompt Injection?

A common solution is to inject the current time into every prompt.

This has several disadvantages:

- The timestamp becomes stale.
- Long-running conversations lose accuracy.
- Every prompt becomes larger.
- The model cannot request updated information when needed.

Using MCP solves these issues.

Hermes simply requests current time information on demand.

The information is always fresh, and prompts remain clean and focused.

---

# Why Use mcp-proxy?

The FastMCP server communicates over stdio.

`mcp-proxy` converts the stdio interface into a Streamable HTTP MCP endpoint, allowing Hermes and other MCP clients to communicate over HTTP without modifying the Python implementation.

This keeps the MCP server simple while supporting modern container-based deployments.

---

# Future Enhancements

Potential additions include:

- Relative time calculations
- Duration calculations
- Business calendar support
- Public holiday lookup
- Natural language date parsing
- Cron utilities
- Sunrise and sunset calculations
- Moon phases
- Time interval arithmetic
- Localization support
- Fiscal calendars
- Workday calculations

---

# Contributing

Contributions are welcome.

Possible areas include:

- Additional MCP tools
- Improved timezone utilities
- Performance improvements
- Test coverage
- Documentation
- Docker optimizations

Please open an issue before submitting large feature changes.

---

# License

Apache-2.0 License

---

# Acknowledgements

This project builds upon:

- Model Context Protocol (MCP)
- Hermes Agent
- FastMCP
- mcp-proxy

Special thanks to the developers and contributors of these projects for providing the foundation that makes interoperable AI tooling possible.

---

# Final Thoughts

Hermes excels at reasoning, planning, and autonomous execution.

What it lacks is direct access to the changing state of the real world.

Time is one of the most fundamental pieces of real-world context.

Hermes Time MCP gives Hermes that missing capability by providing accurate, on-demand access to the host system clock through a clean MCP interface.

Rather than teaching the model what time it is, we give it the ability to ask.