# io.github.heavyblotto/caelus-mcp (remote · www.ephemengine.com)

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

- Trust score: 68/100 (medium)
- Change this week: +4
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `www.ephemengine.com`: 68/100 (this document), [markdown](https://verifymcp.io/servers/heavyblotto-caelus-mcp/api-mcp.md), [page](https://verifymcp.io/servers/heavyblotto-caelus-mcp/api-mcp)
- npm · `caelus-mcp`: 79/100, [markdown](https://verifymcp.io/servers/heavyblotto-caelus-mcp/caelus-mcp.md), [page](https://verifymcp.io/servers/heavyblotto-caelus-mcp/caelus-mcp)

## Channel facts

- Endpoint: `https://www.ephemengine.com/api/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.23.0`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 63/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation not fully verified: no authorisation is required to call this server, and 34 tool(s) never declared a destructiveHint. The MCP spec treats an absent hint as destructive by default, so we cannot call this surface safe.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 72/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 8654 tokens (~233/item across 37 items; 34 tools + 3 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 98/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 95% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.
  - Supports UI / widget rendering.

## Install

### Claude

```bash
claude mcp add --transport http heavyblotto-caelus-mcp https://www.ephemengine.com/api/mcp
```

### Codex

```toml
[mcp_servers.heavyblotto-caelus-mcp]
url = "https://www.ephemengine.com/api/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "heavyblotto-caelus-mcp": {
      "type": "remote",
      "url": "https://www.ephemengine.com/api/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add heavyblotto-caelus-mcp --url https://www.ephemengine.com/api/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  heavyblotto-caelus-mcp:
    url: "https://www.ephemengine.com/api/mcp"
```

### Other

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

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 20 to 23. That category is still filling its 30-day observation window: 6 days of observed history at the previous scan, 7 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 67, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 66, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-28 (score 65, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 64, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 63)

First indexed and scored.

## MCP tools (34)

### `natal_chart` (~341 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `current_sky` (~263 tokens)

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.

Input parameters:

- `date` (string): UTC ISO date-time (convert from local first); omit for now
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number): Latitude, north positive; default 0 makes houses nominal
- `lon` (number): Longitude, EAST positive (Americas are negative); default 0 makes houses nominal
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `sky_view` (~539 tokens)

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.

Input parameters:

- `altitude` (number): Center altitude in degrees: 0 looks at the horizon, positive tilts up
- `azimuth` (number|string, required): Center compass direction: degrees from true north (east positive) or a 16-point name like "W" or "WNW"
- `bortle` (integer): Dark-sky class, 1 (pristine) to 9 (inner city). Sets the night naked-eye limit and drives background star density and Milky Way visibility. Omit for a suburban default
- `date` (string): UTC ISO date-time (convert from local first); omit for now
- `deep_field` (boolean): Pin the complete deep naked-eye star field (thousands of stars at exact pixels) instead of the bright catalog. Larger response; great for control images
- `elevation_m` (number): Eye height above ground in meters (e.g. 9 for a third-floor window)
- `height` (integer): Output image height in pixels
- `include_stars` (boolean): Include bright catalog stars when a star catalog is loaded
- `lat` (number, required): Latitude, north positive
- `lens` (string): Lens preset; sets field of view and projection (ultrawide is fisheye, the rest rectilinear)
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `max_star_mag` (number): Brightest-magnitude cutoff for stars (smaller is brighter); default 2.5, or the limiting magnitude when bortle is set
- `overlays` (array): Reference-frame overlays to project (annotations, not photoreal): the ecliptic line, the zodiac signs, house cusps and angles, and constellation figures. Exact pixels returned in `overlays`
- `width` (integer): Output image width in pixels

### `sky_view_sequence` (~261 tokens)

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.

Input parameters:

- `altitude` (number): Center altitude in degrees
- `azimuth` (number|string, required): Center direction: degrees from true north or a compass name like "W"
- `bortle` (integer): Dark-sky class 1-9
- `date` (string): First frame, UTC ISO date-time; omit for now
- `frames` (integer, required): Number of frames (2-60)
- `height` (integer)
- `lat` (number, required): Latitude, north positive
- `lens` (string)
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `step_minutes` (number, required): Minutes between frames
- `width` (integer)

### `synthetic_validate` (~64 tokens)

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.

Input parameters:

- `system` (object, required)

### `synthetic_positions` (~166 tokens)

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.

Input parameters:

- `date` (string): UT instant as ISO 8601; used as t when t_days is omitted
- `system` (object, required)
- `t_days` (number): Time in the same day units as each body's periodDays/epoch (abstract world frame)

### `synthetic_sky_view` (~246 tokens)

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`.

Input parameters:

- `altitude` (number): Center altitude in degrees
- `azimuth` (number|string, required): Center direction: degrees from true north or a compass name
- `bodies` (array): Body ids to draw; defaults to Sun, Moon, planets, and every synthetic body
- `bortle` (integer)
- `date` (string): UTC ISO date-time; omit for now
- `elevation_m` (number): Eye height above ground in meters
- `height` (integer)
- `include_stars` (boolean): Include catalog stars (usually off for fictional skies)
- `lat` (number, required): Latitude, north positive
- `lens` (string)
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `system` (object, required)
- `width` (integer)

### `transits` (~226 tokens)

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

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `orb` (number): Max orb in degrees
- `transit_date` (string): UTC ISO date-time of transit moment (convert from local first); omit for now
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `synastry` (~137 tokens)

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).

Input parameters:

- `a` (object, required): Person A birth data (UTC date, lat, lon)
- `b` (object, required): Person B birth data (UTC date, lat, lon)
- `orb` (number): Max orb in degrees
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `find_aspect_dates` (~201 tokens)

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).

Input parameters:

- `aspect` (string, required)
- `body` (string, required): Transiting body (snake_case, e.g. saturn, true_node)
- `end` (string, required): UTC ISO end date (convert from local first); range <= 50 years
- `start` (string, required): UTC ISO start date (convert from local first)
- `target_body` (string): Another transiting body. Provide this OR target_lon, not both.
- `target_lon` (number): Fixed natal longitude in degrees. Provide this OR target_body, not both.
- `zodiac` (string): Zodiac for body and target_lon longitudes; tropical (default) or sidereal:<ayanamsa>

### `rectification_grid` (~186 tokens)

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.

Input parameters:

- `date` (string, required): Birth DATE (UTC) as ISO; only the calendar date is used, the time portion is ignored (the window_*_hour fields set the times swept)
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `step_minutes` (number): Minutes between grid rows
- `window_end_hour` (number): Last UTC hour of the date to sweep
- `window_start_hour` (number): First UTC hour of the date to sweep

### `sky_events` (~283 tokens)

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.

Input parameters:

- `body` (string): Required for rise/set/transit/station/crossing
- `end` (string, required): UTC ISO end date; range <= 370 days
- `kinds` (array, required): Event kinds to include
- `lat` (number): Required for rise/set/transit
- `lon` (number): Required for rise/set/transit
- `start` (string, required): UTC ISO start date (convert from local first)
- `target_lon` (number): Zodiac longitude for 'crossing', degrees
- `zodiac` (string): Zodiac for 'crossing' longitudes

### `planetary_hours` (~166 tokens)

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.

Input parameters:

- `date` (string): UTC ISO date-time (convert from local first); omit for now
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)

### `void_of_course` (~123 tokens)

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.

Input parameters:

- `date` (string): UTC ISO date-time (convert from local first); omit for now
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `returns` (~342 tokens)

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).

Input parameters:

- `body` (string, required): sun for the solar return, moon for the lunar return
- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `return_lat`: Latitude for the return chart; defaults to the birth latitude
- `return_lon`: Longitude (EAST positive) for the return chart; defaults to the birth longitude
- `search_end` (string, required): UTC ISO end of the window; range <= 2 years
- `search_start` (string, required): UTC ISO start of the window to search for returns
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `progressions` (~147 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `target_date` (string, required): UTC ISO date to progress/direct to (convert from local first)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `composite` (~187 tokens)

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.

Input parameters:

- `a` (object, required): Person A birth data (UTC date, lat, lon)
- `b` (object, required): Person B birth data (UTC date, lat, lon)
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `dignities` (~226 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `lots` (~187 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `profections` (~220 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `target_date` (string, required): UTC ISO date to profect to (convert from local first)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `firdaria` (~222 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `target_date` (string): UTC ISO date to look up the active period for; omit for the timeline only

### `releasing` (~326 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `horizon_years` (number): timeline length in 360-day years from birth (default 100)
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `lot` (string): the Lot to release from (default spirit)
- `max_level` (integer): deepest sub-period level in the timeline, 1..4 (default 2)
- `target_date` (string): UTC ISO date to read the active L1..L4 periods for; omit for the timeline only
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `directions` (~331 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `include_mundane` (boolean): also return inter-planetary (promissor → significator) directions (default false)
- `key` (string): time key: naibod (0.9856473°/yr, default) or ptolemy (1°/yr)
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `max_years` (number): only directions reached within this many years of life (default 90)

### `nakshatras` (~231 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): sidereal ayanamsa (default sidereal:lahiri); these are sidereal techniques

### `dasha` (~309 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `levels` (integer): deepest timeline level: 1 (maha) or 2 (maha+antar, default)
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `system` (string): dasha system: vimshottari (120y), yogini (36y), or ashtottari (108y)
- `target_date` (string): UTC ISO date to read the active lords for; omit for the timeline only
- `zodiac` (string): sidereal ayanamsa (default sidereal:lahiri); these are sidereal techniques

### `vargas` (~252 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `divisions` (array): subset of 1/2/3/9/10/12/30 (default all)
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): sidereal ayanamsa (default sidereal:lahiri); these are sidereal techniques

### `yogas` (~259 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): sidereal ayanamsa (default sidereal:lahiri); these are sidereal techniques

### `aspect_patterns` (~289 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `chart_signature` (~240 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `chart_facts` (~710 tokens)

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).

Input parameters:

- `anchors` (object): Reference instants for a `relative` when: { anchorId: UTC ISO }
- `constraints` (array): Geometric constraints for an archetypal/conceptual chart with no time (compiler synthesis)
- `date` (string): Exact UTC instant, ISO 8601 (e.g. 1990-06-10T14:30:00Z); convert local to UTC first
- `earliest` (string): Start of an uncertain-time range (UTC ISO); use with `latest` instead of `date`
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `include_vedic` (boolean): With target_date: project nakshatra/varga/yoga (default true when zodiac is sidereal)
- `lat` (number): Latitude, north positive
- `latest` (string): End of an uncertain-time range (UTC ISO)
- `limit` (integer): max facts to return, highest salience first (default 24)
- `lon` (number): Longitude, EAST positive (Americas are negative)
- `realm` (string): What the chart is; frames the interpretation (default observed)
- `target_date` (string): UTC ISO instant for transits and time-lords vs this natal chart; omit for natal-only facts
- `when`: Full structured temporal anchor; overrides date/earliest/latest. Use for relative or narrative time.
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `counterfactual_chart` (~404 tokens)

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.

Input parameters:

- `date` (string, required): UTC date-time, ISO 8601, e.g. 1990-06-10T14:30:00Z. Convert local birth time to UTC first.
- `house_system` (string): House system (default placidus). Case- and spacing-insensitive; valid: placidus, whole_sign, equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus, meridian, polich_page, vehlow (aliase…
- `lat` (number, required): Latitude, north positive
- `lon` (number, required): Longitude, EAST positive (Americas are negative)
- `move_lat`: Recompute at this latitude instead of the birth latitude
- `move_lon`: Recompute at this longitude instead of the birth longitude
- `set_longitudes` (object): Move bodies to these ecliptic longitudes in degrees, e.g. { "mars": 45 }
- `shift_time` (string): Duration to shift the instant: '1h', '-30m', 'P1Y'
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `similar_skies` (~157 tokens)

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.

Input parameters:

- `end` (string, required): UTC ISO end of the search window
- `limit` (integer): max matches to return (default 10)
- `reference_date` (string, required): UTC ISO date whose sky is the target to match
- `start` (string, required): UTC ISO start of the search window
- `step_days` (number): sampling step in days (default 1)

### `electional_search` (~193 tokens)

Rank moments in a window for an electional aim. Samples the window and scores each instant by how closely a set of wanted body-to-body aspects is satisfied (tighter and applying aspects score higher), optionally penalizing a void-of-course Moon. Returns the top moments with the aspects that matched. Body-to-body only; for aspects to the angles, compute the chart at a candidate moment.

Input parameters:

- `avoid_void_moon` (boolean): penalize a void-of-course Moon
- `end` (string, required): UTC ISO end of the window
- `limit` (integer): max moments to return (default 10)
- `start` (string, required): UTC ISO start of the window
- `step_hours` (number): sampling step in hours (default 6)
- `wanted` (array, required): aspects to reward when close to exact
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

### `cosmic_weather` (~130 tokens)

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.

Input parameters:

- `date` (string, required): UTC ISO date
- `window_days` (number): days either side to scan for stations (default 7)
- `zodiac` (string): tropical (default) or sidereal:<ayanamsa>

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/heavyblotto-caelus-mcp/api-mcp#diagnostics

## Score history

- 2026-08-03: 68
- 2026-08-02: 68
- 2026-08-01: 67
- 2026-07-31: 67
- 2026-07-30: 66
- 2026-07-29: 65
- 2026-07-28: 65
- 2026-07-27: 64
- 2026-07-26: 63

## Links

- Remote endpoint: https://www.ephemengine.com/api/mcp
- Repository: https://github.com/heavyblotto/caelus
- Changelog RSS feed: https://verifymcp.io/servers/heavyblotto-caelus-mcp/api-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/heavyblotto-caelus-mcp/api-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/heavyblotto-caelus-mcp/api-mcp