Purpose
gnomon-mcp is a small MCP (Model Context Protocol) server positioned as a collection of tools that "models all need but are boring and essential": dates, calendars, arithmetic, and unit conversion. Its purpose is to stop assistants from making "next-token guesses" about math and date math. LLMs are by default not good at arithmetic and date calculations, and often give plausible-sounding but slightly wrong answers, a type of error that is hard to notice in long responses. gnomon-mcp exposes deterministic Python implementations through MCP, enabling models to calculate rather than guess.
The principle for deciding when to use gnomon is: when "the next most likely token" is not the correct answer. Specific scenarios include: math that needs to be taken seriously (any calculation beyond simple mental arithmetic, involving decimal points, or requiring accumulation) — call calc; determining "what date is it today," "how much longer," "how much time has passed" — the model's training cutoff is not today, so call now to get a snapshot, use calendar's until / since / diff to calculate elapsed time, and use parse to parse natural-language dates (such as "next thursday"); date arithmetic across months/years (adding 30 days, finding the end of a quarter, calculating business days) — models are often off by one, so call calendar's add / business_days; unit conversion (such as kg to lb, °C to °F) — call calc_convert, do not eyeball it; row-by-row table workloads — when the same calculation needs to be applied to every row of a table, both batch tools (calendar, calc) accept lists and return lists in order, getting N results in one call. Rule of thumb: if you would ask a colleague to "double-check that number," then call gnomon instead.
Main capabilities
now(tz?)
A standalone tool that returns a rich dictionary snapshot of the current moment. One call gives you all the information about "right now." According to the documentation, now(tz?) returns 18 fields, including ISO week, quarter, fiscal year, day of the year, is_weekend, and more, not just {iso, tz}.
calendar(ops)
A batch dispatcher. Each entry chooses its own operation. Designed for row-by-row table workloads, for example calculating elapsed time for each row in one call. The operations supported by calendar(ops) are add, business_days, until, since, diff, parse, etc. The units for diff / until / since support seconds, minutes, hours, days, weeks. Built-in natural language date parsing (such as "next thursday" "in 3 hours"), no separate NLP server needed.
calc and calc_convert
calc is used for expression evaluation; calc_convert is used for unit conversion, based on Pint. Both support batching: calc(expressions) accepts a list of expressions.
The documentation gives an example: computing multiple things in a single call.
Comparison with other MCP servers
There are already multiple MCP servers for time and math, including the official Time reference implementation (time zones only), mcp-time and mcp-datetime (date formatting / time zones), calculator-server (math + units, no dates), and bundled tools like agent-utils-mcp (regex / hashing / JWT). gnomon's positioning is narrower: batch-first, calendar(ops) and calc(expressions) accept lists, covering an entire spreadsheet column in one tool call instead of N calls; provides a true now(), returning 18 fields in one call; integrates dates, math, and units in the same place, with no need to combine three separate servers; built-in natural language dates, with no separate NLP server needed. If you only need time zone conversion, the official Time server is enough; if you want a broad bundle of tools (regex, hashing, encoding, JWT), agent-utils-mcp is more suitable; gnomon is aimed at the boring core of date arithmetic and arithmetic, and provides it in a batch manner.
Usage
Installation-free is recommended, running on demand via uv: uvx gnomon-mcp. Or install globally: gnomon-mcp. All integration recipes assume the use of uvx gnomon-mcp; if you prefer a fixed installation, you can replace the command with gnomon-mcp (without uvx).
When integrating with an agent, you can edit ~/.claude.json or the project .mcp.json; claude_desktop_config.json; ~/.cursor/mcp.json (or .cursor/mcp.json within the project); ~/.continue/config.yaml. Any other client (generic stdio): start uvx gnomon-mcp as a subprocess and communicate over MCP via stdin/stdout — that is the entire integration.
Hosted / remote (HTTP transport): suitable for team-shared instances or agents that cannot start a local subprocess; then point the MCP client at http://<host>:8000/mcp (or /sse for SSE transport).
Getting agents to actually use it
MCP tool descriptions are deliberately terse to minimize persistent context overhead (all four tools are about 150 tokens). The richer "when to use gnomon" guidance lives in an on-demand-loaded Claude Code skill.
Option A — Claude Code plugin (one command, recommended): the plugin wires up the MCP server and the skill in one go. After using the command inside Claude Code, it registers gnomon as an MCP server (auto-started via uvx) and installs the on-demand skill. The skill body is loaded only when a task triggers it, keeping persistent context at roughly 150 tokens for the four tool descriptions plus about 40 tokens for the skill name and summary.
Option B — Manual skill installation (without the plugin): if you have already wired up the MCP server via claude mcp add gnomon -- uvx gnomon-mcp and only want to install the skill, you can install it manually.
Option C — Paste into the system prompt (non-Claude Code agents): for agents that do not support skills, you can paste a short version into the system prompt or CLAUDE.md.
Future tools (sketch)
Same logic — if a model might bluff, expose a deterministic version — pointing to more primitives worth building. None of the following are implemented yet; this is a candidate list, roughly ordered by value for effort: text measurement count(text, unit) for characters / words / lines / sentences / LLM tokens, since agents often miscount "how long is this" and "will it fit in the context window"; regex match / replace regex_find(pattern, text) and regex_sub(pattern, repl, text), since models hallucinate which substrings match a regex and a real engine can settle the argument; structured data extraction jq(path, json) / jsonpath(path, json) to read values from nested data by path and avoid typos; hashing and encoding hash(text, algo) (sha256, md5, blake2), encode(text, scheme) / decode(text, scheme) (base64, hex, url, jwt-payload), all of which models confidently get wrong; Decimal money math money(expr), evaluated with explicit rounding under Python Decimal, because calc is float-based and not safe for money; holiday-aware business days, extending calendar.business_days with a country (or calendar) parameter to exclude US / UK / India holidays, since the current implementation only recognizes weekends; Cron description / next fire times cron_describe("0 9 * * 1-5") to human English and cron_next(expr, n) to return the next N fire times, since models often misread cron fields; token counting for a target model count_tokens(text, model) via tiktoken / Anthropic tokenizer, so agents can budget prompts and outputs themselves instead of guessing. If you want any of these, open an issue or PR — each is a small self-contained module that fits the existing tools/ layout.
When it applies
Scenarios that need deterministic math, date arithmetic, cross-month/cross-year handling, business day calculation, unit conversion, and natural language date parsing; especially tasks that require row-by-row batch computation over tables. If you only need time zone conversion or a broad tool bundle (regex, hashing, encoding, JWT), other specialized MCP servers may be more suitable.
Limitations
As mentioned in the text, all candidate features in the future tools section are not yet implemented; the current business_days only recognizes weekends and does not exclude holidays; calc is float-based and not safe for money. Other limitations not described in the materials are not provided for now.
