About caelus-mcp
caelus-mcp is an MCP server for astrology calculations, built around the Caelus TypeScript engine. It serves users and developers who need charts, transits, timing methods, Vedic calculations, and citable chart facts; the project describes its implementation as clean-room and without Swiss Ephemeris code or ephemeris files.
Key features
- 01Chart and transit calculations
- 02Synastry, events, and eclipses
- 03Hellenistic timing techniques
- 04Vedic methods
- 05Citable chart facts and sky-view frames
Use cases
- 01Generate an astrology chart
- 02Examine transits or eclipses
- 03Calculate synastry between charts
- 04Produce chart facts for citation
MCP support
The `caelus-mcp` package provides MCP tools for charts, transits, synastry, events, and eclipses.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://www.ephemengine.com/api/mcpclaude mcp add --transport http heavyblotto-caelus https://www.ephemengine.com/api/mcp{"mcpServers":{"heavyblotto-caelus":{"type":"http","url":"https://www.ephemengine.com/api/mcp"}}}Open in Cursor{"servers":{"heavyblotto-caelus":{"type":"http","url":"https://www.ephemengine.com/api/mcp"}}}Open in VS Code{"mcpServers":{"heavyblotto-caelus":{"type":"http","url":"https://www.ephemengine.com/api/mcp"}}}{"mcpServers":{"heavyblotto-caelus":{"serverUrl":"https://www.ephemengine.com/api/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
35| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | Yes | Latitude, north positive |
| lon | number | Yes | Longitude, EAST positive (Americas are negative) |
| date | string | Yes | UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first. |
| grid | enum | No | Canonical grid (with output:'canonical'): arcsec (default), milliarcsec, centideg, dms ([deg,min,sec] triples), or accuracy (each body snapped to its measured validated accuracy — the most portable choice for cross-platform content addressing)arcsec | milliarcsec | centideg | dms | accuracy |
| output | enum | No | 'float' (default) returns the usual floating-point payload. 'canonical' returns integers on a declared grid plus a sha256 digest: stable across machines/browsers/languages, hashable for caching and dedupe, precision-honest, with sign/house/aspects re-derived from the quantized values so displayed numbers and facts always agreefloat | canonical |
| zodiac | enum | No | tropical (default) or sidereal:<ayanamsa>tropical | sidereal:lahiri | sidereal:fagan_bradley | sidereal:krishnamurti | sidereal:raman | sidereal:yukteshwar | sidereal:galcent_0sag | sidereal:true_citra |
| remainders | enum | No | With output:'canonical': also return the remainder set — the integer sub-quantum residues quantization discarded, keyed by leaf path and bound to the payload digest. 'auto' picks one grid finer than the base; or name the refinement grid (must be strictly finer). Residues telescope: composeRemainders(payload, remainders) rebuilds the finer-grid payload exactly. Time residues are integer microseconds, distance residues integer nano-AUauto | arcsec | milliarcsec |
| separation | enum | No | Aspect separation: 'longitude' (default, the zodiacal aspect) or 'spatial' (true great-circle separation accounting for ecliptic latitude — differs for the Moon, Pluto, and bodies far off the ecliptic)longitude | spatial |
| house_system | string | No | House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliases like "whole sign" also work). |
Details
From the project READMECaelus
Clean-room astrology computation monorepo. MIT, no Swiss Ephemeris code, no AGPL, no ephemeris files. Caelus computes ephemeris positions, charts, events, hellenistic timing techniques, Vedic methods, citable chart facts, sky-view image-prompt frames, and the MCP tools around them. Live at ephemengine.com.
Packages
| Path | npm | Description |
|---|---|---|
packages/caelus | caelus | TypeScript engine (~153 KB gzipped total, zero deps) |
packages/caelus-mcp | caelus-mcp | MCP server: charts, transits, synastry, events, eclipses |
packages/caelus-delineations-pd | — | Public-domain interpretation corpus + default validation set for interpret() |
packages/birth | caelus-birth | Birth time + place → UT (timezone and DST resolution) |
packages/wheel | caelus-wheel | React SVG chart wheel, zero runtime deps |
apps/web | — | Next.js site: playground, validation, edge /api/chart |
caelus-starter | — | Next.js starter app (separate repo) |
The Python reference engine and data-fitting pipeline live in python/;
they mint the coefficient data and golden fixtures and are not a runtime
dependency.
Docs
- ARCHITECTURE.md — layout, durability decisions, product strategy
- MCP_SPEC.md — MCP tool contract
- docs/gap-analysis.md — Swiss Ephemeris comparison (closed at 0.5.0)
- docs/agents.md — pitfalls for coding agents building on Caelus
- docs/releasing.md — release process
Quick start
npm install
npm run build
npm test
npm run dev -w web
http://localhost:3000 — live chart in the browser.
Edge API: GET /api/chart?date=…&lat=…&lon=….
Branches
main— stable releasesdev— active development
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.