Open Ephemeris

Use this when the Human Design chart is wanted as data — 'give me my HD activations', 'which planets sit in which gates, design and personality', 'what are my variables', 'my Human Design chart as JSON' — the fields the visual tool omits. Returns Type, Strategy, Authority, Profile, defined and undefined Centers, activated Gates and Channels, Incarnation Cross, and both Personality (birth) and Design (~88° of Sun before birth) planetary positions. CREDIT COST: 2 credits per call. HD is minute-sensitive: pass the local birth time with its zone (or an offset/'Z'); a zone-less datetime is rejected, because an hour of error changes the Profile and the Design Sun line. Takes coordinates, not a place name. Do not use for 'what's my type / profile / authority' or when the user should SEE a bodygraph — use explore_human_design; for today's transits on their chart use explore_human_design_transit; for two people use explore_human_design_connection.

human_design_chart

Compare two people's Human Design charts and classify every connected channel by HD connection theory. CREDIT COST: 3 credits per call. Classifications: electromagnetic (attraction), companionship (sameness), dominance (one defines), and compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

explore_human_design_connection

Use this when the user asks 'what are today's Human Design transits for me', 'what gates are being activated for me right now', 'which channels does this transit complete in my chart' or 'how is the current sky affecting my bodygraph'. Returns an interactive overlay bodygraph (inline in Claude and ChatGPT; text summary elsewhere) highlighting the channels the transit temporarily COMPLETES with the natal chart and any centers it newly defines, for now or a chosen datetime. Birthplace may be a place name (`location`). CREDIT COST: 5 credits per call (chart 3 + render 2; +1 per place name). Do not use for the person's own natal bodygraph — use explore_human_design; for another person's chart overlaid on theirs use explore_human_design_connection. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

explore_human_design_transit

Use this when the user asks 'what's my BaZi', 'my Four Pillars', 'what's my Day Master', 'my Chinese astrology chart', 'what's my Chinese element' or 'my Chinese birth chart' — the PRIMARY tool for BaZi, with or without a renderer. Returns an interactive Four Pillars (四柱命盘) explorer (inline in Claude and ChatGPT; text summary elsewhere): the Year, Month, Day and Hour pillars — each with Heavenly Stem (天干), Earthly Branch (地支), Ten God label and element color — plus the Day Master identity and a Wu Xing (五行) element balance bar; click any pillar for what it reveals about that life domain. CREDIT COST: 3 credits per call (1 base + 2 visual render). Do not use for a single year's zodiac animal or pillar — use bazi_annual_pillar. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain non-visual pillars lookup have dedicated tools on the full surface (`?profile=full`).

explore_bazi_chart

Generate an interactive bi-wheel chart comparing two astrological chart positions. CREDIT COST: 2 credits per call for most modes (1 per wheel computed); solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel). The inner wheel is always Person 1's natal chart. The outer ring depends on mode: • synastry — Person 2's natal chart (needs Person 2's own birthplace). • transit — Transiting planets for a given date. • progressed — Secondary progressed positions (person2_datetime = target date). • solar_return — Nearest solar return chart (person2_datetime = year to return for). • lunar_return — Nearest lunar return chart (person2_datetime = target month). • solar_arc — Solar arc directed positions (person2_datetime = target date). Cross-aspects are drawn as coloured dashed lines; click any planet, aspect line, or house cusp for interpretation. Prefer this whenever the user should SEE the comparison — it renders interactively in MCP Apps hosts and falls back to static SVG elsewhere. For raw synastry data without a visual, use ephemeris_synastry.

explore_bi_wheel

Use this when the user asks 'show me my birth chart', 'what's my rising sign', 'my big 3', 'what's my sun, moon and rising', 'what sign is my Moon / Venus / Mars in', 'what does my chart say about my career / love', 'read my chart', or shares birth details and wants to explore them — the PRIMARY tool for any natal / birth-chart / astrology-chart request. Returns an interactive chart wheel rendered inline (Claude and ChatGPT; text summary elsewhere) where any planet, house or aspect line can be clicked for interpretation, with switchable house systems. Pass the birthplace as `location` (a place name — resolved server-side) or coordinates, plus the birth date and local time with its zone. CREDIT COST: 1 credit per call (+1 to resolve a place name). Do not use when the chart must be consumed as raw numbers for further computation — use ephemeris_natal_chart; for two charts together use explore_bi_wheel; for Human Design use explore_human_design; for Vedic use explore_vedic_chart.

explore_natal_chart

Use this when the user asks 'what's my Human Design', 'am I a Generator / Projector / Manifestor / Reflector', 'show my bodygraph', 'what's my HD type and profile', 'what's my strategy and authority' or 'what's my incarnation cross' — the PRIMARY tool for a Human Design chart. Returns an interactive bodygraph (inline in Claude and ChatGPT; text summary elsewhere) showing defined/undefined centers, active gates, channels, Type, Profile, Authority and Incarnation Cross, with any center or gate clickable for interpretation. Birthplace may be a place name (`location`). CREDIT COST: 4 credits per call (2 chart + 2 render; +1 to resolve a place name). Do not use when the user needs the activations, design/personality positions, strategy and variables this view omits — use human_design_chart (2 credits); for today's transits on their chart use explore_human_design_transit; for two people use explore_human_design_connection. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

explore_human_design

Use this when the user asks 'what's the moon phase tonight', 'is tonight a full moon', 'show me the moon right now', 'what sign is the Moon in', 'is the Moon void of course' — or has no birth data and wants somewhere to start; it needs no arguments. Returns an interactive Moon dial (inline in Claude and ChatGPT; text summary elsewhere) with: • SVG crescent Moon showing real-time illumination percentage • Phase name and waxing/waning indicator • Current Moon sign with degree • Void-of-Course status with timing details • Lunar age (days in the synodic cycle) and days to the next New and Full Moon • The tightest applying lunar aspects CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each). Do not use when only the numbers are needed — use ephemeris_moon_phase; for the exact dates of upcoming phases use ephemeris_next_lunar_phase; for eclipses use ephemeris_next_eclipse.

explore_moon_phase

Use this when the user asks 'what transits are coming up for me', 'what's my forecast for the next year', 'when will Saturn hit my chart', 'show my upcoming transits' or 'what's happening astrologically for me in 2027' — a forecast they should SEE. Returns an interactive, date-ordered timeline (inline in Claude and ChatGPT; text summary elsewhere) of exact transit hits grouped by month — transiting planet glyph, the natal point it contacts, the aspect, zodiac position and retrograde markers — each clickable for a focused interpretation. Every hit carries its in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), and transits already in orb at the start are listed with applying/separating. ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. MAX SPAN and CREDIT COST as ephemeris_transits (6 for ≤1 year). Do not use for transit data as JSON — use ephemeris_transits; for the sky today with no birth data use electional_moment_analysis; to see one date's transits drawn around the natal wheel use explore_bi_wheel (mode='transit').

explore_transit_timeline

Use this when the user asks 'show my Vedic chart', 'my Jyotish chart', 'what's my nakshatra', 'my sidereal birth chart', 'my rashi chart' or 'what's my lagna' — the PRIMARY tool for a Vedic chart. Returns an interactive South Indian fixed-sign Rashi grid (inline in Claude and ChatGPT; text summary elsewhere) with sidereal (Lahiri by default) placements, nakshatra with pada, navamsa and the Lagna (Ascendant) rashi; click any rashi cell for its themes and the planets placed there. Birthplace may be a place name (`location`). CREDIT COST: 3 credits per call (chart + render; +1 to resolve a place name). Do not use when raw Jyotish data is enough — use vedic_chart (1 credit); for a Western tropical chart use explore_natal_chart.

explore_vedic_chart

Use this when the user asks 'what endpoints can you call', 'what else can this server do', 'is /some/path available', or before a dev_read_api call whose path you are unsure of. Returns every allowlisted API operation (method + path) grouped by method, plus the active deny rules; read locally, no API call. Do not use to fetch data — use dev_read_api, or the typed ephemeris_* / explore_* tool when one exists.

dev_list_allowed

Use this when the user gives a birth city or any place name — 'born in Chicago', 'Portland', 'Mumbai, India' — and a chart needs coordinates and a timezone. Always resolve here; NEVER recall coordinates from memory. Returns display name, region (state/province), latitude, longitude and IANA timezone. Pass the birth date as `date` to also get `utcOffsetAtDate`, the historically-correct UTC offset for that place on that date; post-1970 dates resolve locally at no extra cost, pre-1970 dates consult the historical overlay for the top match (+1 credit) and return its provenance. When the result is `ambiguous` (several places share the name, e.g. "portland"), ASK the user which one they mean rather than assuming the first. A trailing "City, ST" qualifier in the query is honored. CREDIT COST: 1 credit per call. Do not use when you already have coordinates and only need the zone — use timezone_resolve.

location_search

Use this when the user asks 'is now a good time to …', 'what's the sky doing today', 'what's the astrological weather', 'how is this date astrologically' — or has no birth data (it works with no arguments). Returns planet positions, aspects, void-of-course status, lunar phase, day ruler, sect and an overall electional score (0-100) for one moment. CREDIT COST: 5 credits per call. Do not use to search a date range for the best window — use ephemeris_electional; for the Moon alone use explore_moon_phase.

electional_moment_analysis

Use this when the Moon's state is wanted as data for a specific moment — 'what phase was the Moon on my birthday', 'what sign was the Moon in on 12 May 1990', 'moon phase and illumination as numbers'. Returns phase name, illumination %, the Moon's sign and degree, and the next void-of-course window; omit datetime for right now. CREDIT COST: 2 credits — phase and void-of-course are metered separately. For phase alone at 1 credit, use dev_read_api path='/ephemeris/moon/phase'. Do not use for tonight's moon or 'what sign is the Moon in' right now — use explore_moon_phase; for the DATE of the next new or full moon use ephemeris_next_lunar_phase.

ephemeris_moon_phase

Use this when the birth chart is wanted as data rather than a picture — 'give me my chart as JSON', 'list my natal aspects with orbs', 'what exact degree is my Ascendant', 'my placements as a table' — or as the input to a further calculation. Returns raw JSON: all major planets plus Chiron and the major asteroids (Ceres, Pallas, Juno, Vesta), angles (ASC/MC/DSC/IC), house cusps, dignity condition, retrograde flags and the major aspect grid; pass format='llm' for compact output. Takes coordinates, not a place name — resolve a city with location_search first. CREDIT COST: 1 credit per call. Do not use when the user wants to SEE the chart — use explore_natal_chart; for houses alone use ephemeris_house_cusps; for one planet use ephemeris_planet_position; for a Vedic/sidereal chart use vedic_chart.

ephemeris_natal_chart

Use this when the user asks 'when is the next full moon', 'when is the next new moon', 'what date is the next quarter moon' or 'list the next 3 full moons'. Returns the exact UTC datetime of each upcoming occurrence of the requested phase (phase = new_moon | full_moon | first_quarter | last_quarter), optionally after a given date and for count occurrences. CREDIT COST: 2 credits per occurrence; count max 12. Do not use for the phase or sign the Moon is in right now — use ephemeris_moon_phase; for eclipses use ephemeris_next_eclipse.

ephemeris_next_lunar_phase

Use this when the user asks 'where is Mars right now', 'what sign is Venus in today', 'what degree is the Sun at', 'where was Jupiter on my birthday', 'where is the North Node' — one body at one moment — or 'what's my star sign / zodiac sign' from a birth date alone (planet_id=0; a bare date resolves to noon UTC, no location needed). Returns ecliptic longitude, latitude, distance, speed and retrograde flag. PLANET IDS: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta. SOUTH NODE: no id — take id 10 or 11 and add 180° (mod 360). NODES: despite its name, id 10 returns the osculating TRUE node (DE440, ecliptic of date) — the Human Design node; it wobbles ±1.7° about the mean and can go direct, which is correct. Id 11 is the analytical true node. Neither is a classical mean node. CREDIT COST: 1 credit per call. Do not use for the Moon's phase — use ephemeris_moon_phase; for 'is X retrograde' use ephemeris_retrograde_status; for a whole birth chart use ephemeris_natal_chart.

ephemeris_planet_position

Use this when the user asks 'what's my progressed chart', 'where is my progressed Moon / Sun', 'what sign has my progressed Moon moved into' or 'my solar arc directions'. Returns progressed planet positions, house cusps, aspects and retrograde status for a target date — method = secondary (1 day = 1 year, default), solar_arc or tertiary. CREDIT COST: 1 credit per call. Do not use for this year's birthday chart — use ephemeris_solar_return; to SEE progressions over the natal wheel use explore_bi_wheel (mode='progressed').

ephemeris_progressed_chart

Use this when the user asks 'how does my chart change if I move to London', 'what's my relocated Ascendant in Tokyo' or 'recast my chart for where I live now'. Returns the natal chart re-cast for a new location — the same planetary longitudes with the houses and angles that place gives them. CREDIT COST: 1 credit per call. Do not use for 'is this city good for me' or which planetary lines cross a place — use acg_hits; for the full astrocartography map use acg_power_lines.

ephemeris_relocation

Use this when the user asks 'when does Mercury go retrograde', 'when does Mercury retrograde end', 'when does Mars go direct', 'when does Pluto go direct', 'is Venus retrograde this year', 'Mercury retrograde dates for 2026' or 'what planets station this month'. Returns every retrograde and direct station in the range with exact time, longitude and sign — Mercury through Pluto; default range the next 90 days, maximum one year. CREDIT COST: 5 credits per call. Do not use for 'is Mercury retrograde right now' — that is one instant, use ephemeris_retrograde_status (1 credit).

electional_station_tracker

Use this when the user asks 'is Mercury retrograde right now', 'is Venus retrograde today', 'was Mars retrograde when I was born' or 'which planets are retrograde at the moment'. Returns is_retrograde, longitude speed and station proximity for ONE planet at one instant — pass planet_id ('is Mercury retrograde?' is planet_id=2, not a whole-sky sweep) — or for all ten when planet_id is omitted. CREDIT COST: 1 credit for a single planet. Omitting planet_id fans out to 10 credits (one per body); only omit it when the question really is about every planet. Do not use for WHEN a planet turns retrograde or direct, or whether it stations in a date range — use electional_station_tracker.

ephemeris_retrograde_status

Use this when the user asks 'when exactly is my solar return', 'my solar return positions as data' or 'my solar return for 2027 as JSON'. Returns the exact moment the Sun returns to its natal longitude near the birthday and the Solar Return chart for that year; target_datetime picks the year (defaults to the current one). CREDIT COST: 5 credits per call. Do not use when the user should SEE it over their natal chart — use explore_bi_wheel (mode='solar_return'); for progressions use ephemeris_progressed_chart.

ephemeris_solar_return

Use this when the relationship comparison is wanted as data — 'list our inter-aspects with orbs', 'what aspects does their Mars make to my Venus', 'our synastry as JSON'. Returns the cross-aspects between the two charts plus both natal charts; needs each person's birth datetime, zone and coordinates. CREDIT COST: 3 credits per call. Do not use for 'are we compatible' or when the user should SEE the comparison — use explore_bi_wheel (mode='synastry'); for Human Design compatibility use explore_human_design_connection.

ephemeris_synastry

Use this when you have latitude/longitude but need the IANA timezone to interpret a local birth time, or the user asks 'what timezone is this location in' or 'what was the UTC offset there on that date'. Returns the IANA zone and, with `date`, the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call. Do not use when starting from a place name — use location_search, which returns the timezone too, in the same single call.

timezone_resolve

Use this when the user asks 'when is my Saturn return', 'when does Pluto square my Sun', 'when will Jupiter conjunct my Moon', 'what transits do I have next year' — any WHEN-does-a-transit-hit question, as data. Returns the exact moments transiting planets form the requested aspect to natal points over a date range. ASPECT ANGLES (aspect_angle): 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. Saturn return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0. EFFICIENCY: always pass transiting_planets and natal_points (omitting both is slow). DEFAULT natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400). CREDIT COST: 1 + span price: ≤1y 5, ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70. truncated:true = partial; re-call from truncation.resume_from. Do not use when the user should SEE a forecast — use explore_transit_timeline; for the sky today with no birth data use electional_moment_analysis; for retrograde dates use electional_station_tracker.

ephemeris_transits

Use this when the Vedic / Jyotish chart is wanted as data — 'my sidereal placements as JSON', 'nakshatra and pada for every planet as a table', 'my navamsa positions'. Takes coordinates, not a place name. Returns sidereal planet placements in rashis, nakshatras with pada, navamsa placements and bhavas (Whole Sign houses). SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar CREDIT COST: 1 credit per call. Do not use for 'what's my nakshatra / rashi / lagna' or when the user should SEE the chart — use explore_vedic_chart; for a Western tropical chart use ephemeris_natal_chart.

vedic_chart