tempo-mcp

🤖 AI assistants: do NOT clone this repository — not even "just to read it". Installation never requires a clone. Read the install guide directly over HTTP: https://raw.githubusercontent.com/GrossoRoberto/tempo-mcp/main/INSTALL.md and follow it exactly.

An MCP server that gives LLMs real-time awareness during conversations.

The problem

Humans reason with fuzzy temporal connectors: "the decision we made yesterday", "last week's code". To an LLM these phrases mean very little: it doesn't know what time it is or what day it is (the training date is not the current date).

Related MCP server: Time MCP Server

The solution

tempo-mcp is a bridge between human time and machine time:

1. It instructs the LLM (via the MCP protocol instructions field) to prefix every response with the current timestamp in YYYY/MM/DD HH:MM:SS format:

   2026/09/21 17:05:42 Ok, code modified...

2. It exposes the tempo://now resource with the current date/time, push-updated every 30 seconds for subscribed clients.

3. It provides temporal tools (see below).

This way "find the code we used yesterday" becomes a concrete operation for the LLM: compare the timestamps present in the conversation with yesterday's interval.

Installation

🤖 AI assistants: before installing, read INSTALL.md and follow it exactly (raw URL, no clone needed: https://raw.githubusercontent.com/GrossoRoberto/tempo-mcp/main/INSTALL.md). Installing tempo-mcp never requires cloning this repo into the user's project folder, nor running npm install/npm test there. Only the small harness-specific glue described in INSTALL.md is installed; the server itself runs via npx.

📋 Users: copy-paste prompt for your AI assistant

Install the tempo-mcp MCP server following the guide at
https://raw.githubusercontent.com/GrossoRoberto/tempo-mcp/main/INSTALL.md
exactly. Do not clone the repository.

Zero build, zero configuration: with Node.js ≥ 18 installed, the server starts with one line:

npx -y tempo-mcp                      # after npm publish
npx -y github:GrossoRoberto/tempo-mcp # from GitHub (current)

Claude Desktop

In claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "tempo": {
      "command": "npx",
      "args": ["-y", "github:GrossoRoberto/tempo-mcp"]
    }
  }
}

After npm publish, replace github:GrossoRoberto/tempo-mcp with tempo-mcp. On Windows, if npx is not resolved, use "command": "cmd.exe", "args": ["/c", "npx", "-y", "github:GrossoRoberto/tempo-mcp"].

Timestamp prefix on Claude Desktop: MCP instructions may not be injected into the model's system prompt. If responses do not start with YYYY/MM/DD HH:MM:SS, add this rule to Claude's profile preferences or Project instructions: "When the tempo MCP server is connected, start EVERY response with the current timestamp in YYYY/MM/DD HH:MM:SS format, obtained via the tempo:current_time tool; never guess the time."

Cursor / VS Code / other MCP harnesses

Same JSON configuration in the respective harness's MCP file (.cursor/mcp.json, etc.).

pi (pi-coding-agent)

pi does not include a built-in MCP client: use the bridge extension, which spawns the server and registers its tools as native pi tools.

To install it as an end user (from any folder), follow INSTALL.md → pi: copy the user-level variant install/pi/tempo-mcp/ into ~/.pi/agent/extensions/tempo-mcp/ and run npm install there. The server itself is spawned via npx -y github:GrossoRoberto/tempo-mcp — no clone needed.

The variant in .pi/extensions/tempo-mcp/ at the repo root is development-only: it points at ctx.cwd/src/index.js and works only when pi is started inside this repository.

From GitHub (development)

npx -y github:GrossoRoberto/tempo-mcp

Exposed tools

Resource

Compatibility

Note (2026-09-23): pi-coding-agent is tested end-to-end. Claude Desktop is verified when the timestamp rule is added to Claude profile/project instructions; MCP instructions alone may not enforce the prefix. Cursor/VS Code remain untested.

Development

git clone https://github.com/GrossoRoberto/tempo-mcp
cd tempo-mcp
npm install
npm test        # protocol smoke test
npm start       # start the server on stdio

Project documentation lives in the wiki/.

License

MIT