@numcal/mcp

MCP server for the numcal date and time calculator. Gives LLM tools (Claude Code, Claude Desktop, Cursor, Continue, and any other Model Context Protocol client) deterministic date math via a single natural-language tool.

Most LLMs are unreliable on arbitrary calendar questions — days-between, business-days, DST edges, non-Gregorian calendars, country-specific holidays, leap years, ISO week numbers, moon phases. This server hands those questions to numcal's parser + evaluator and returns the answer with every assumption attached, so the model can quote a verified result instead of guessing.

Install

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "numcal": {
      "command": "npx",
      "args": ["-y", "@numcal/mcp"]
    }
  }
}

Claude Code

claude mcp add numcal -- npx -y @numcal/mcp

Anything else

Run npx @numcal/mcp over stdio. Any MCP-compliant client works.

What you get

One tool: calculate(query: string, locale?: string, today?: string).

The query accepts every phrasing numcal understands — see numcal.com/help for the full grammar. Some examples:

days between today and 2026-12-25
months between 2026-01-01 and 2026-07-01
Jun 1 2026 + 30 business days
age of 1990-06-15   ·   when will I turn 40 born 1990-06-15
what day of the week is July 4 2026   ·   week number of today
days until christmas   ·   days since 2000-01-01
when is easter 2027   ·   is 2026-07-04 a holiday in US
5pm Tokyo in New York   ·   current time in Tokyo
3:45 + 2:30   ·   90 minutes in hours
every Friday for 12 weeks
next full moon   ·   when is the next eclipse   ·   spring equinox 2026   ·   perseids 2026
moon phase on 2026-07-04   ·   today in hebrew
what quarter is it   ·   which is sooner, christmas or new year

The response includes:

• A headline answer ("227 days", "Friday", "April 4, 2027")
• Supporting context (the dates involved, the weekday, derived breakdowns)
• The full assumption row — calendar system, locale, country holidays applied, DST handling, year inference. Quote these back to the user; that's the audit trail.

License

MIT. The web tool at numcal.com stays free.