Deepnatal MCP server

deepnatal

A natal chart engine that cross-verifies every result three independent ways — and refuses to answer when it can't.

Ships as both a TypeScript library and an MCP server for Claude, Cursor, Codex, Cline and other agents.

npx -y deepnatal-mcp

Why this exists

Ask any astrology site for a birth chart and you get an answer. You almost never get a way to check it.

That matters more than it sounds, because the ascendant — the rising sign — moves about one degree every four minutes. Get the UTC instant wrong by an hour and it shifts by roughly half a sign. The result still looks completely plausible. Nothing about it announces that it's wrong.

And an hour is easy to lose. Taiwan observed daylight saving in 1945–1961 and again in 1974–1979. Mainland China did from 1986 to 1991. Japan did from 1948 to 1951. Plenty of tools quietly apply today's UTC offset to a 1988 birth date and hand back a chart that's off by exactly one hour.

This package is built around the opposite assumption: a result you can't check is not a result.

How it verifies

Three independent paths compute every chart. Disagreement is an error, not something to average away.

Typical agreement in practice is under one arcminute. Past tolerance, the call throws rather than returning a chart.

It also degrades honestly where the math genuinely breaks down:

• Above 66° latitude, Placidus houses are undefined. The engine falls back to whole-sign and tells you it did, instead of emitting silent nonsense.
• Without a birth time, the ascendant, midheaven and houses are simply omitted with reasons. No substituting noon. If the Moon changed sign that day — which happens on nearly half of all dates — that's reported too.
• Inside a DST transition gap, where a local time either doesn't exist or happens twice, it throws and asks you to disambiguate.

Verify it yourself

A README asserting "cross-verified" is worth nothing on its own. The suite ships inside the published package, so you can run it against the exact bytes you installed:

npm i deepnatal
node node_modules/deepnatal/dist/selftest.js

✅ PASS — 21/21 boundary cases + 11/11 external cross-checks
   All three paths agree, and they agree with an outside source.

The 21 boundary cases are chosen to be the ones that break things, not the ones that are easy: China's 1986–1991 DST window and a same-year winter control, Taiwan 1979, Japan's 1948–1951 GHQ period, a time that never existed because a DST jump skipped it, and latitudes inside the Arctic Circle where Placidus is undefined.

The 11 external checks compare against values captured from astro-seek. Those exist because the three internal paths share assumptions — tropical zodiac, apparent geocentric positions, true ecliptic of date — and if an assumption itself were wrong, all three would agree on the same wrong answer. Only an outside source catches that.

CI runs the suite on Node 20/22/24 under a deliberately non-UTC system clock, so any accidental dependence on the host timezone fails loudly.

Quick start

npm install deepnatal

import { calculateNatalChart, verifyAscendant } from 'deepnatal';

Shortened. The full README is on GitHub.