Literature Clock MCP

A line for the current minute, from literature, copyright-free books, or an original voice.

mcp model-context-protocol mcp-server literature-clock ink-clock quotes books voices stdio streamable-http cursor vscode claude

Client pages

clients/ is a set of HTML pages for Cursor, VS Code, Claude Desktop, a browser that calls get_quote, a page that subscribes to the quote push on GET /events, and a page that reads and changes settings. Open clients/index.html, or serve the folder on localhost so those pages can reach the server.

Add the server

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "literature-clock-mcp": {
      "command": "npx",
      "args": ["-y", "literature-clock-mcp"]
    }
  }
}

VS Code — user or workspace mcp.json

{
  "servers": {
    "literature-clock-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "literature-clock-mcp"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows

{
  "mcpServers": {
    "literature-clock-mcp": {
      "command": "npx",
      "args": ["-y", "literature-clock-mcp"]
    }
  }
}

This repository is the project home. It does not contain the server source. Install the published package with the npx blocks above.

Add a hosted server

The same configs work for Render, IBM Code Engine, or any host that serves this app over HTTPS. The MCP URL is the site plus /mcp. The live Render server is https://literature-clock-mcp.onrender.com/mcp. A Code Engine app looks like https://<app>.<region>.codeengine.appdomain.cloud/mcp.

The host must run MCP_MODE=http HOST=0.0.0.0 npx -y literature-clock-mcp@1.6.5 and leave PORT for the platform. Deploy steps for Render are under Render.

When auth mode is write or all, add a header Authorization: Bearer <key>. Auth is off on a fresh server, so the blocks below need no key.

Cursor — this project: .cursor/mcp.json. Every project: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "literature-clock-mcp": {
      "url": "https://literature-clock-mcp.onrender.com/mcp"
    }
  }
}

Save the file. Open Cursor Settings → MCP and turn literature-clock-mcp on. A green dot means the handshake worked. In Agent chat, ask: ask literature-clock-mcp for the current quote.

VS Code — workspace .vscode/mcp.json, or Command Palette → MCP: Open User Configuration.

{
  "servers": {
    "literature-clock-mcp": {
      "type": "http",
      "url": "https://literature-clock-mcp.onrender.com/mcp"
    }
  }
}

Command Palette → MCP: List Servers → start literature-clock-mcp. In Copilot Chat, confirm the server is selected in the tools list, then ask for the current quote.

Claude Desktop — the desktop file only starts a local process. mcp-remote opens the hosted URL. Config path: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Quit Claude and open it again after you save.

{
  "mcpServers": {
    "literature-clock-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://literature-clock-mcp.onrender.com/mcp"]
    }
  }
}

The first call after a free Render instance has been idle can take a moment while the process wakes. The clock on the server is that machine’s clock. On Render that is UTC, so “now” is four hours ahead of Toronto.

An MCP server that tells the time the way a literature clock does: one sentence that names that exact minute.

The default source is Literature, Johannes Enevoldsen's literature-clock collection (CC BY-NC-SA 2.5). Books are copyright-free lines bundled with the server. The other sources are original voices written for this clock, not quotations from films or living authors.

No account and no analytics. Books and voices stay on the machine. Literature tries those bundled exact-minute lines first, then the public collection, and falls back to copyright-free books if the library does not answer.

Screenshots

The HTTP clock, with Literature selected for 11:11.

An original voice, not a book quotation.

Settings (laptop sign-in demo / demo). Default source, time zone, 12-hour or 24-hour clock, users and passwords, auth, and rate limit.

Sign-in before Settings on a fresh session.

Features

Quote sources

list_sources returns the live catalog, including each voice id.

Tools

get_schema for a tool includes inputSchema, outputSchema, and the next call. Follow that next field once. describe_server returns server.version and server.description. The same version is in the page header, on Health, in get_settings, and in the server schema.

get_quote is read-only. Pass avoid with the previous line text to get a different line for the same minute. count is 1–8. Failures set isError: true. An empty lines array means that minute has no row — try literature, books, or mix. Do not invent a quotation.

Example:

{ "time": "09:05", "source": "literature" }

Quote push

The schedule is off until an interval and a destination are saved. The HTTP process sends the current quote from the saved source and time zone. A matching minute is :00, :05, :10, and so on. stdio does not run the schedule. A chat client does not print a push. Call get_quote for a line in the reply.

clientPush lets a client call push_quote without waiting for the minute. That call always includes the event stream, plus any other saved destination. Turn it on under Settings → Push, or with update_settings and "clientPush": true. The Events page has Push a quote now, which calls push_quote. Subscribe first, then press it.

Settings → Push → Push a quote now uses the saved destinations only. Save the schedule before that button. It does not turn clientPush on.

The clock on a host is that machine’s time zone setting. timeZone device is the process zone. On Render that is UTC.

Resources and prompts

Run

Published package:

npx literature-clock-mcp                 # stdio
MCP_MODE=http npx literature-clock-mcp   # http://127.0.0.1:8080/health

The same settings are get_settings / update_settings, and GET or POST /api/settings.

The browser UI is HTTP only. stdio does not open a page. MCP_MODE=http npx literature-clock-mcp@1.6.5 serves the clock. The local desk port in development is http://127.0.0.1:8788/.

Render

render.yaml starts the published npm package. This repository does not contain the server source. Leave PORT unset so Render can set it. Bind 0.0.0.0.

Start command

MCP_MODE=http HOST=0.0.0.0 npx -y literature-clock-mcp@1.6.5

Health check path: /health.

The clock is https://<your-service>.onrender.com/. The MCP URL is that host plus /mcp. Settings sign-in uses ADMIN_USER (default demo) and ADMIN_PASSWORD. The laptop password demo is off on that public address. IDE setup for that URL, and for Code Engine, is under Add a hosted server.

Example

In Cursor, with literature-clock-mcp.onrender.com connected:

ask literature-clock-mcp for the current quote

The Literature Clock on Render answered for 16:01, the clock on that server. That is 12:01 PM in Toronto.

A little after four o’clock, Pippa meandered over to Dot’s house carrying a bottle of wine she had been keeping in reserve and wondering if she could possibly be pregnant in spite of the vestigial coil still lodged in her uterus like astronaut litter abandoned on the moon.

The Private Lives of Pippa Lee, by Rebecca Miller. The time phrase is “A little after four o’clock.” The source was Literature.

Auth

Auth defaults to off. Settings and Log show a lock because they need a sign-in.

Issue and revoke keys on /admin. /health only means the process is up; /test runs the quote checks.

Settings → Backup downloads the clock, auth, protocols, schedule (including client push), tool gates, and saved users (password hashes). Import restores that file. API keys and the MQTT password are not in it. Log → Export log and trace downloads counters, errors, the call trace, and the audit trail.

Settings → Tool gates can disable a tool or lock it so it needs a credential even when auth is off. describe_server stays available and stays open.

Settings → Users adds a name and password with scopes read, write, or admin. The built-in admin name comes from ADMIN_USER and is not replaced here. Settings → API keys issues a bearer key. The secret is shown once.

Settings → Protocols turns stdio, Streamable HTTP, and SSE on or off. At least one stays on. The same tab can hide the HTML pages until sign-in. describe_server and update_settings still answer on a protocol that is on, so a turned-off transport can be turned back on.

Publish

Publish from the package that contains src/ and data/, not from this git tree. See docs/PUBLISHING.md. The npm tarball ships src/, data/ (books and voices), the README, docs/screenshots/, docs/icon.png, docs/icon.svg, server.json, clients/, LICENSE, and NOTICE.

npm keywords: mcp, model-context-protocol, mcp-server, literature-clock, ink-clock, quotes, books, voices, stdio, streamable-http, cursor, vscode, claude, clock.

Related clocks

Author

Markus van Kempen · github.com/markusvankempen

No bug too small, no syntax too weird.