Almanac MCP server

almanac

Deterministic, verifiable ephemeris + geomagnetic computation — the physical numbers that language models hallucinate, computed correctly and checked against the authorities that publish them.

Two pure-compute cores, no API keys, no network for the math, same inputs → same bytes:

Magnetic Model 2025: magnetic declination (the angle a compass reads off true north), inclination, intensity, the X/Y/Z vector, and secular variation, for any location/altitude/date. Pure Python standard library — zero dependencies.*

• almanac.geomag — the Earth's magnetic field from the official **World

Sun/Moon/planet altitude–azimuth–distance, rise/set/transit, the four twilight phases, moon phase + illumination, ecliptic ("zodiac") longitude, day length, next new/full moon and next equinox/solstice, for any location/time.

• almanac.ephemeris — the sky from the public-domain JPL DE421 kernel:

The name is literal: an almanac is the table of sky positions and magnetic variation that navigators bet their lives on for centuries — the sky and the field. This is that, made machine-checkable.

Why this exists

Ask a language model "what's the magnetic declination at 40°N 105°W in 2026?" or "where's the Moon over Tokyo right now?" and it will answer — confidently, and usually wrong. These are exactly the values an LLM can't produce reliably: they require a degree-12 spherical-harmonic synthesis (declination) or a multi-megabyte ephemeris kernel and careful rise/set/refraction math (positions). Getting them wrong points a ship, a drone, or a survey the wrong way.

almanac doesn't guess. It computes — deterministically — and the correctness is provable, not asserted:

Correctness (the whole point)

geomag is a faithful port of NOAA's geomag70 reference algorithm; the proof is the authority grading our independent synthesis against its own numbers. Run it yourself:

pip install -e ".[dev]"
pytest -q
# tests/test_geomag.py ....... 107 passed   (the 100 NOAA points + edge cases)
# tests/test_ephemeris.py .... 7 passed     (cross-engine + known-truth)

Quickstart

pip install -e .          # geomag works immediately (stdlib only)
                          # ephemeris pulls in skyfield + the public-domain DE421 kernel

from almanac.geomag import compute as field
from almanac.ephemeris import compute as sky

# Magnetic declination in Boulder, CO, mid-2026 — what your compass is off by:
f = field(lat=40.015, lon=-105.27, when="2026-06-26")
print(f["declination_deg"], "-", f["compass_note"])
# 7.6892 - magnetic north is 7.69 deg east of true north

# The sky over New York at a given instant:
s = sky(lat=40.7128, lon=-74.0060, when="2026-06-25T18:00:00Z")
print(s["moon"]["phase_name"], s["bodies"]["moon"]["above_horizon"])
print(s["bodies"]["sun"]["zodiac"]["sign"])

Every result is a plain JSON-serializable dict, fully labeled with units, and deterministic — the same query returns the same bytes, every time, on any machine.

API

almanac.geomag.compute(lat, lon, altitude_km=0.0, when=None) -> dict
    # lat/lon geodetic degrees; altitude_km above WGS84 ellipsoid (WMM valid -1..850);
    # when = ISO date/datetime, a bare decimal year like "2027.5", or "now"/None.
    # WMM2025 is valid 2025.0–2030.0. Declination positive = east of true north.

Shortened. The full README is on GitHub.