Caelus Mcp

io.github.heavyblottoPublished by GitHub account heavyblottov0.24.1Updated Oct 24, 2026

34-tool Caelus MCP for validated astrology: charts, transits, Vedic, facts, sky view, synthetic.

VerifiedStreamable HTTPWeb executable

Overview

AI-generated overview

An astrology computation server that lets an assistant cast natal and event charts, compute transits, Vedic and Hellenistic techniques, and sky-view frames.

What you can do
Cast and compare charts: natal charts, current sky, synastry, composite and Davison charts, returns, progressions, and perturbed or similar-sky variants, plus ranked citable chart facts and structural signatures. Compute timing and events: transits, aspect dates, sky events such as rise/set, phases, eclipses and stations, planetary hours, void-of-course Moon, and electional ranking. Apply traditional and Hellenistic techniques: dignities, Hermetic lots, profections, firdaria, zodiacal releasing, primary directions, parans, and aspect patterns. Apply Vedic methods: nakshatras, dasha periods, divisional charts, and yogas. Frame the sky: sky view and sky view sequences for image prompts, plus a
When to use it
Use it when an assistant needs computed astrological charts and derived facts rather than free-form interpretation, for natal readings, transit and electional timing, Vedic or Hellenistic analysis, or generating sky-view image prompts. It suits users who want structured, citable chart data.
Requirements
Runs as a remote endpoint or as a local npm package over stdio, so a local install needs Node.js. No authentication, environment variables or headers are declared. Chart tools need birth date, time, latitude and longitude; sky events need a location.
Before you install
Tools return computed positions and counts, not interpretation, so readings depend on the assistant. Birth data such as date, time and place is personal information sent to the server. Some tools default to a geocentric location when no place is given, which makes houses and angles nominal.

Installation

In SourceWeft

  1. Open Caelus Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.heavyblotto%2Fcaelus-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "caelus": {
      "type": "http",
      "url": "https://www.ephemengine.com/api/mcp"
    }
  }
}

README

Caelus

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

PathnpmDescription
packages/caeluscaelusTypeScript engine (~153 KB gzipped total, zero deps)
packages/caelus-mcpcaelus-mcpMCP server: charts, transits, synastry, events, eclipses
packages/caelus-delineations-pd—Public-domain interpretation corpus + default validation set for interpret()
packages/birthcaelus-birthBirth time + place → UT (timezone and DST resolution)
packages/wheelcaelus-wheelReact 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

Quick start

bash
npm installnpm run buildnpm testnpm run dev -w web

http://localhost:3000 — live chart in the browser. Edge API: GET /api/chart?date=…&lat=…&lon=….

Branches

  • main — stable releases
  • dev — active development

Source: README.md at commit b5631d4

Tools

35

natal_chart

A person's birth chart. Requires their exact birth date+time and birthplace (all three: date, lat, lon). Use this — not current_sky — whenever the question is about someone's natal/birth chart. Returns 13 bodies (sun–pluto, chiron, nodes) with sign, house, retrograde, speed; ASC/MC; cusps; major aspects with orb, applying/separating phase, and strength (1=exact). Vs Swiss Ephemeris (1850–2150): Sun–Saturn ≤1″, Uranus ≤1.9″, Neptune ≤4.6″, Moon ≤2.5″, Pluto ≤3.4″ (Chebyshev pack), Chiron ≤1″, mean node ≤1″, true node ≤ 1′ vs SE's built-in ephemeris.

Parameterslatrequiredlonrequireddaterequiredgridoutputzodiacremaindersseparationhouse_system

current_sky

The sky at a moment and place — not tied to any person. Use for "what's the sky/transits right now" or the chart of a non-birth event. Date defaults to now; lat/lon default to 0,0 (geocentric on the equator at the prime meridian), where houses and ASC/MC are nominal — pass a real location if houses matter. For a specific person's birth chart use natal_chart instead. Returns positions, houses, retrogrades, aspects.

Parameterslatlondategridoutputzodiacremaindersseparationhouse_system

sky_view

Where the visible bodies land in a framed photo of the sky, for an image prompt. Give a place, a moment, an aim (compass direction and altitude), a lens, and an image size; get each in-frame body's pixel position, apparent size, brightness, the Moon's phase orientation, a sky-state summary (twilight, limiting magnitude, horizon row), the bright bodies just outside the frame, a ready-to-use prompt, and a machine-readable `renderPlan` (a body-free background-plate prompt plus the computed layers to composite locally, for a hybrid render pipeline). Caelus computes the geometry and photometry; it does NOT render the image. For "at sunset", first find the set time with sky_events, then pass it as date.

Parameterslatrequiredlonrequireddatelenswidthbortleheightazimuthrequiredaltitudeoverlaysdeep_fieldelevation_m+2 more

sky_view_sequence

A time sequence of sky frames for an animation: the same place, aim, and lens stepped through time. Returns a compact per-frame timeline (instant, twilight, Sun/Moon altitude, Moon phase + bright-limb, whether the Milky Way is in frame) plus the fixed celestial pole and the sky's sidereal rotation per frame. Each frame's full pixel-accurate spec comes from calling sky_view at that instant; this tool plans the timeline. Use for sunset-to-night transitions, star-trail planning, or Moon-phase progressions.

Parameterslatrequiredlonrequireddatelenswidthbortleframesrequiredheightazimuthrequiredaltitudestep_minutesrequired

synthetic_validate

Check an authored synthetic celestial system for ill-defined inputs: duplicate body ids, non-positive periods, out-of-range eccentricity, or a dangling observer. Returns `impossible` and a list of problems — the same honesty pattern as compileForm.

Parameterssystemrequired

synthetic_positions

Positions of every body in an authored synthetic system at one instant. Three body modes: `placement` (fixed longitude), `periodic` (uniform motion), `kepler` (constant elements). With `observer` set on the system, positions are geocentric/apparent from that body (outer bodies can show retrograde). Pass `t_days` for abstract day units, or `date` (UT ISO) when body `epoch` values are Julian Days. Returns speed and retrograde per body.

Parametersdatesystemrequiredt_days

synthetic_sky_view

Sky View for a mix of real and synthetic bodies: register the authored system on an ephemeral engine, then frame the visible sky like sky_view. Synthetic bodies can carry render attributes (sizeDeg, magnitude, color) that flow into the pixel spec and prompt. Real Sun/Moon/planets stay for twilight and context unless omitted from `bodies`.

Parameterslatrequiredlonrequireddatelenswidthbodiesbortleheightsystemrequiredazimuthrequiredaltitudeelevation_m+1 more

transits

Transiting planets vs natal chart: aspects within orb (applying/separating), natal house per transiting body.

Parameterslatrequiredlonrequiredorbdaterequiredzodiachouse_systemtransit_date

synastry

Compare two people's birth charts: inter-chart aspects with orbs, house overlays both ways, plus ranked citable fact atoms and a ready `brief` (synastry/composite ids for auditCitations). Each person needs date+lat+lon. House overlays always use Placidus (not configurable here).

Parametersarequiredbrequiredorbzodiac

find_aspect_dates

Exact dates a transiting body makes an aspect, within a range: to a fixed longitude OR to another transiting body. Provide exactly one of target_lon / target_body. Includes retrograde re-hits. Body names are snake_case (mean_node, true_node).

Parametersendrequiredbodyrequiredstartrequiredaspectrequiredzodiactarget_lontarget_body

rectification_grid

Rectification sweep: ASC/MC at each step across a window of UTC hours on one date, with ASC sign-change times. Use when the birth time is unknown and you want candidate times. The sweep runs over window_start_hour..window_end_hour (UTC hours of the given date); the date's time portion is ignored.

Parameterslatrequiredlonrequireddaterequiredstep_minuteswindow_end_hourwindow_start_hour

sky_events

Sky events in a UTC date range: rise/set/meridian transits (need lat+lon+body), lunar phases (new/quarters/full), solar and lunar eclipses, stations (body turns retrograde/direct; needs body), zodiac degree crossings (needs body + target_lon). Solar eclipses report global circumstances (type, magnitude, gamma) plus the greatest-eclipse location and path width; add lat+lon to also get local circumstances (type seen, magnitude, obscuration, contact times C1-C4). Lunar eclipses report type and magnitude; add lat+lon to learn whether the Moon is above the horizon there. Times to the second vs Swiss Ephemeris (stations to ~1 min: ill-conditioned by nature). Range <= 370 days.

Parametersendrequiredlatlonbodykindsrequiredstartrequiredzodiactarget_lon

planetary_hours

Planetary hours for a moment and place: the unequal hour in effect (its ruler, day/night, hour number 1-24, start/end UTC), the ruler of the planetary day, and the full 24-hour ruler sequence. Hours split the day (sunrise to sunset) and night (sunset to next sunrise) into twelve each; the day ruler is the weekday ruler and the hours follow the Chaldean order. Needs lat+lon. Returns available:false above the polar circles when the Sun does not rise or set that day.

Parameterslatrequiredlonrequireddate

void_of_course

Void-of-course Moon at a moment: whether the Moon makes no further Ptolemaic aspect to a traditional planet (Sun..Saturn) before it leaves its current sign. Returns the Moon's sign, the UTC time it exits that sign, and the UTC time of its next perfecting aspect (null when none remains -- i.e. void). Tropical by default.

Parametersdatezodiac

returns

Solar or lunar return: the instant(s) a body returns to its natal longitude within a window, plus the full return chart for the first one. The Sun returns about yearly (the solar-return chart for the year), the Moon about monthly. Return chart is cast for the return moment at return_lat/return_lon (defaults to the birthplace; pass the current/relocated place for a relocated return).

Parameterslatrequiredlonrequiredbodyrequireddaterequiredgridoutputzodiacremaindersreturn_latreturn_lonsearch_endrequiredhouse_system+1 more

progressions

Secondary progressions (day-for-a-year) and solar-arc directions of a natal chart to a target date. Returns, per body, the secondary-progressed longitude and the solar-arc-directed longitude, plus the solar arc itself. Longitudes only (no houses), so no birthplace is needed.

Parametersdaterequiredzodiactarget_daterequired

composite

Relationship charts for two people: the midpoint composite (each body and angle is the shorter-arc midpoint of the two natal positions) and the Davison chart (a real chart cast for the midpoint in time and place). Each person needs date+lat+lon.

Parametersarequiredbrequiredzodiachouse_system

dignities

Essential dignity and sect for the seven traditional planets at a moment and place. Per planet: its sign, any essential dignity (domicile/exaltation/detriment/fall), its weighted essential-dignity score (Lilly: rulership 5, exaltation 4, triplicity 3, term 2, face 1; detriment -5, fall -4) with a peregrine flag, its planetary sect (diurnal/nocturnal, null for Mercury), and whether it is in sect given a day or night chart. The chart is day when the Sun is above the horizon — so lat+lon are required.

Parameterslatrequiredlonrequireddaterequiredzodiac

lots

The seven Hermetic lots (Arabic parts) — Fortune, Spirit, Eros, Necessity, Courage, Victory, Nemesis — cast from the Ascendant and reversing direction by sect (a chart is day when the Sun is above the horizon). Per lot: its longitude and zodiacal position. Lots are anchored to the Ascendant, so an exact time and lat+lon are required. Fortune and Spirit are mirror images about the Ascendant. Tropical by default.

Parameterslatrequiredlonrequireddaterequiredzodiac

profections

Annual and monthly profections (a Hellenistic time-lord technique) at a target date. The natal Ascendant advances one whole sign per year of life; the profected sign's traditional ruler is the lord of the year, the single most important time-lord for that year. Returns the age in years, the month within the profection year, and the annual and monthly profected sign (with its whole-sign house from the natal Ascendant and its lord). Needs the birth time and place for the Ascendant.

Parameterslatrequiredlonrequireddaterequiredzodiactarget_daterequired

firdaria

Firdaria (firdariyyat): the Persian/medieval planetary time-lord periods. Life divides into nine major periods totalling 75 years — the seven planets (a day chart starts with the Sun, a night chart with the Moon) then the North and South Nodes — each planetary period split into seven sub-periods. Returns the full timeline (each period and sub-period with UTC start/end) and, when target_date is given, the major and sub lord active then. Sect is taken from the birth chart, so lat+lon are required; pure time arithmetic, no zodiac.

Parameterslatrequiredlonrequireddaterequiredtarget_date

releasing

Zodiacal releasing (aphesis), the Hellenistic time-lord technique from Vettius Valens, released from a Lot (Spirit by default, or Fortune). From the Lot's sign, periods release sign by sign with planetary minor-year lengths on the 360-day-year convention; each level is a twelfth of the one above (L1..L4), and a loop back to the starting sign looses the bond, jumping once to the opposite sign (+6). Returns the timeline down to max_level over the horizon and, when target_date is given, the L1..L4 lords active then. Anchored to the natal Lot, so an exact time and lat+lon are required.

Parameterslatrequiredlonrequiredlotdaterequiredzodiacmax_leveltarget_datehorizon_years

directions

Primary (mundane) directions of the seven traditional planets to the four angles (MC, IC, Ascendant, Descendant), and optionally between the planets themselves. The diurnal rotation carries a body to the angle (or a promissor to a significator); the arc of rotation, converted by a time key (Naibod 0.9856473°/yr by default, or Ptolemy 1°/yr), gives the age of the direction. Returns the directions within max_years, sorted by age, each with its arc, age in years, and UTC date. With include_mundane, also returns the planet-to-planet (promissor → significator) directions. Circumpolar bodies have no Ascendant/Descendant directions. Needs the birth time and place; equatorial, so zodiac is irrelevant.

Parameterskeylatrequiredlonrequireddaterequiredmax_yearsinclude_mundane

nakshatras

The nakshatra (one of the 27 lunar mansions of 13°20′) of each classical point on the sidereal zodiac: the seven traditional planets and the Ascendant (lagna). Per point: the nakshatra name, its pada (quarter, 1–4), the ruling planet (the Vimshottari lord), and degrees into the nakshatra. The Moon's nakshatra (janma nakshatra) anchors the Vimshottari dasha. Sidereal by definition; Lahiri ayanamsa by default. Needs the birth time and place for the Ascendant.

Parameterslatrequiredlonrequireddaterequiredzodiac

dasha

Vedic dasha periods — planetary time-lord cycles started from the Moon's birth nakshatra. system selects Vimshottari (120-year, the standard), Yogini (36-year, eight yoginis), or Ashtottari (108-year). Returns the period timeline (mahadasha → antardasha) with UTC start/end, the balance of the first period at birth, and — when target_date is given — the lords active then (Vimshottari also gives the pratyantardasha). Sidereal; Lahiri by default. Needs the birth time and place.

Parameterslatrequiredlonrequireddaterequiredlevelssystemzodiactarget_date

vargas

Parashari divisional charts (vargas): the sign of each of the seven planets and the Ascendant in the requested D-charts — D1 rasi, D2 hora, D3 drekkana, D9 navamsa, D10 dasamsa, D12 dwadasamsa, D30 trimsamsa. Per point in each chart: the divisional sign and the division number within the rasi. The navamsa (D9) is the most consulted after the rasi. Sidereal; Lahiri by default. Needs the birth time and place for the Ascendant.

Parameterslatrequiredlonrequireddaterequiredzodiacdivisions

yogas

Vedic yogas (planetary combinations) on the sidereal rasi chart: the five Pancha Mahapurusha yogas (Ruchaka, Bhadra, Hamsa, Malavya, Shasha), Gajakesari, Budha-Aditya, and Chandra-Mangala; whether Kemadruma (the isolated-Moon yoga) is present; the raja yogas (a kendra lord associating with a trikona lord) and dhana (wealth) yogas, each as the lord pair and how they associate (conjunction, aspect, or exchange); and the chart's yogakarakas (a planet ruling both a kendra and a trikona). Sidereal; Lahiri by default. Needs the birth time and place.

Parameterslatrequiredlonrequireddaterequiredzodiac

aspect_patterns

Classical aspect configurations in a chart: T-squares, grand trines, grand crosses, yods, kites, mystic rectangles, and stelliums by sign and by house. Each is a structured object with the participating bodies and the worst defining-aspect orb; T-squares and yods also name the apex, stelliums their sign or house. Reported patterns are maximal — a grand cross hides the T-squares it contains, a kite its grand trine. Pure geometry (engine orbs plus a quincunx for yods), no interpretation. Needs date, lat, lon.

Parameterslatrequiredlonrequireddaterequiredzodiachouse_system

parans

Parans (paranatellonta): co-angular bodies over the 24 hours from a date at a latitude — every pair of bodies simultaneously on one of the four angles (rising, culminating, setting, anti-culminating) within a stated tolerance. The relationship behind Brady's fixed-star parans, computed for the moving bodies; pure positional astronomy over the validated rise/set/transit times. Longitude-independent: latitude alone fixes the geometry, so only lat is needed. Date defaults to now.

Parameterslatrequireddatebodiesoutputtolerance_min

chart_signature

A chart's structural signature as plain counts: element, modality, angularity, quadrant, and hemisphere distributions over the bodies; the dominant element, modality, and most-occupied sign; and the classical chart ruler (the ruler of the Ascendant's sign). Counts only, no interpretation — a compact summary for emphasis and comparison. Needs date, lat, lon.

Parameterslatrequiredlonrequireddaterequiredzodiachouse_system

chart_facts

A chart's validated facts as ranked, citable atoms for interpretation. Each fact has a stable id (e.g. "aspect:moon~neptune:conjunction"), the bodies it concerns, a salience score (luminaries, angular placements, the chart ruler, tight/hard aspects, configurations rank high), and a plain-language statement. Facts span placements, aspects, configurations, the structural signature, dispositors and receptions, a body's tight conjunction with a bright fixed star (e.g. "star:jupiter:Sirius"), and the Part of Fortune and Spirit (e.g. "lot:fortune"). Read the facts, write the interpretation in your own words, and cite the [id] each statement rests on — do not introduce facts not listed. Returns the ranked facts plus a ready-to-interpret `brief`. By default a real birth chart: pass date+lat+lon. The chart's grounding is first-class via `realm` (what it is: observed/forecast/fictional/mythic/archetypal/…) and the time: an exact `date`, an uncertain `earliest`+`latest` range (the brief then frames it as provisional and trusts the Moon/angles/houses less), `constraints` for an archetypal chart with no time (synthesized via the compiler), or a full structured `when` (relative-to-another-event or a narrative calendar). A `when` of kind `relative` looks its `anchorId` up in `anchors` (a map of id → UTC instant supplied in the request). Omit lat+lon for a placeless chart (nominal houses).

Parameterslatlondatewhenlimitplacerealmwherelatestzodiacanchorsearliest+5 more

counterfactual_chart

A birth chart, perturbed — a 'what if'. Give a base chart (date+lat+lon) and an edit: `shift_time` (e.g. '1h', '-30m', 'P1D') moves the instant ("born an hour later"), `move_lat`+`move_lon` recompute at another place, and/or `set_longitudes` moves bodies to new ecliptic degrees ("Mars in the next sign"). Returns the diff vs the original: bodies that changed sign or house, aspects gained or lost, and angles that changed sign. A time/place edit rotates the houses and angles while planets stay put; a longitude splice moves only those bodies and recomputes their aspects.

Parameterslatrequiredlonrequireddaterequiredzodiacmove_latmove_lonshift_timehouse_systemset_longitudes

similar_skies

Find when the sky most resembled a reference moment. Builds a feature vector for the reference date's planetary configuration and scans a window for the closest matches by cosine similarity (1.0 = identical configuration). Answers 'when did the sky last look like this?' for transit echoes and historical analogues. Returns the top matches with their similarity, highest first.

Parametersendrequiredlimitstartrequiredstep_daysreference_daterequired

cosmic_weather

The mundane sky on a date: the active aspect configurations among the transiting planets (T-squares, grand trines, grand crosses, yods, kites, mystic rectangles, stelliums by sign), any planet stationing within a window, and whether the Moon is void of course. A 'cosmic weather' snapshot; no birth chart or location needed.

Parametersdaterequiredzodiacwindow_days

Version history

1
  1. v0.24.1LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts