Open Ephemeris

Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type (Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions. Returns raw JSON. For a user-facing interactive bodygraph, use explore_human_design instead. CREDIT COST: 2 credits per call. Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion before birth (~3 months prior, the Design calculation). The API handles this automatically. The datetime must state its zone — pass an offset/'Z', or pass local time plus timezone. A zone-less datetime is rejected rather than assumed to be UTC: Human Design is minute-sensitive, and an hour of error changes the Profile and the Design Sun line. EXAMPLE (local birth time + zone): someone born 15 April 1990 at 14:30 in Chicago: datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298 EXAMPLE (already in UTC): datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298

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

Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph. CREDIT COST: 3 credits per call. Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it newly defines — the core of a Human Design transit reading. Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude and ChatGPT), with a text summary fallback elsewhere. Premium (Pro tier). Calculated with 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_transit

Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars. Returns an embedded visual Four Pillars explorer showing the Year, Month, Day, and Hour pillars — each with its Heavenly Stem (天干) and Earthly Branch (地支), Ten God label, and element color — plus the Day Master identity and a Wu Xing (五行) element balance bar. Click any pillar for an instant interpretation of what it reveals about that life domain (Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life). CREDIT COST: 3 credits per call (1 base + 2 visual render). Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude and ChatGPT). Falls back to a text summary in other hosts, so it is also the right call without a renderer. 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

PRIMARY tool for any natal/birth-chart request. Renders an interactive, clickable chart wheel — prefer this over ephemeris_natal_chart when the user wants to SEE a chart. Returns an embedded visual chart explorer that lets you click any planet, house, or aspect line for instant astrological interpretation. CREDIT COST: 1 credit per call. Supports house system switching (Placidus, Whole Sign, Equal, Koch). The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. Renders interactively in MCP Apps-capable hosts (Claude and ChatGPT) and falls back to static SVG in other hosts.

explore_natal_chart

Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels. CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the visual), 2 in text-only hosts that skip the render. For chart data alone at 2 credits — including the activations, design, personality, strategy and variables this tool does not return — use human_design_chart. Returns an embedded visual bodygraph explorer that lets you click any center or gate for instant Human Design interpretation. Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, and Incarnation Cross. The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. Use this instead of human_design_chart for a richer, interactive HD experience in MCP Apps-capable hosts (Claude and ChatGPT). Falls back to a text summary in other hosts. Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.

explore_human_design

Generate an interactive Moon Phase dial showing the current lunar illumination, phase name, zodiac sign, and void-of-course status as a beautiful circular visualization. Returns a visual dial 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) • Upcoming New Moon and Full Moon dates CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each). Use this instead of ephemeris_moon_phase for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude and ChatGPT). Falls back to a text summary in other hosts.

explore_moon_phase

Generate an interactive Transit Timeline — a vertical, date-ordered list of upcoming transit hits (transiting planets forming a chosen aspect to natal chart positions) over a date range. Returns a visual timeline with: • Exact crossing dates grouped by month • Transiting planet glyph, the natal point it contacts, and the aspect • Zodiac position of each crossing and retrograde markers • Click any transit for a focused interpretation 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. DEFAULT natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years. CREDIT COST: 6 credits per call (natal chart + predictive transit search). Use this for a rich, interactive transit-forecast experience in MCP Apps-capable hosts (Claude and ChatGPT). Falls back to a text summary in other hosts.

explore_transit_timeline

Generate an interactive Vedic (Jyotish) birth chart as a South Indian fixed-sign Rashi grid, with clickable rashis showing sidereal placements, nakshatras, and the Lagna. CREDIT COST: 3 credits per call (chart calculation + visual render). Returns an embedded visual explorer that lets you click any rashi cell for its themes and any planets placed there. Shows sidereal (Lahiri by default) planet placements, nakshatra with pada, navamsa, and the Lagna (Ascendant) rashi. Uses NASA JPL DE440 ephemerides. Use this for a rich, interactive Jyotish experience in MCP Apps-capable hosts (Claude and ChatGPT). Falls back to a text summary in other hosts.

explore_vedic_chart

List all API operations (method + path) that this MCP instance is authorized to call. Returns endpoint entries grouped by method, plus the active deny rules. Use this to discover what's available before calling dev_read_api, or to verify an endpoint path. Typed shortcut tools (ephemeris_natal_chart, ephemeris_transits, etc.) cover the most common operations — check those first before reaching for the generic proxies.

dev_list_allowed

Resolve a place name to coordinates and IANA timezone — use this first whenever a user gives a birth city rather than latitude/longitude. NEVER recall coordinates from memory; always resolve them here. CREDIT COST: 1 credit per call. 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 (1987 DST rules differ from today's). Post-1970 dates resolve locally and cost no extra credits; a pre-1970 date consults the API's historical correction overlay for the top match (1 extra credit) and returns its provenance — tzRuleSource, tzRuleCitation, tzOverlayVersion. 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. Optional bias params (country/region/near) improve ranking; a trailing "City, ST" qualifier in the query is also honored.

location_search

Analyze the astrological quality of a specific moment: planet positions, aspects, void of course status, lunar phase, day ruler, sect, and an overall electional score (0-100). Perfect for evaluating whether 'right now' or a specific date/time is good for action. CREDIT COST: 5 credits per call. EXAMPLE: Analyze March 21, 2026 at noon in New York: date='2026-03-21T12:00:00Z', latitude=40.7128, longitude=-74.0060

electional_moment_analysis

Get the Moon's current phase angle, illumination, sign and void-of-course status AT a specific point in time. Returns phase name (New, Waxing Crescent, etc.), illumination %, the zodiac sign and degree the Moon occupies, and next void-of-course period. ⚠️ THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' and 'What sign is the moon in?' ❌ THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?' → For upcoming phase DATES use ephemeris_next_lunar_phase instead. For a user-facing interactive moon-phase dial, use explore_moon_phase instead. 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'. If no datetime is provided, returns the current (live) moon phase.

ephemeris_moon_phase

Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for interpretation (available on all tiers). The result includes all major planets, Chiron and major asteroids like Ceres, angles (ASC/MC/DSC/IC), essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included. Returns raw JSON. For a user-facing visual chart, use explore_natal_chart instead. CREDIT COST: 1 credit per call. EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago — pass the local time and name the zone: datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298 Equivalently, put the zone on the datetime: datetime='1990-04-15T14:30:00-05:00' (or the UTC instant '1990-04-15T19:30:00Z').

ephemeris_natal_chart

Find the next occurrence of a specific Moon phase after a given date. Returns the exact UTC datetime of each occurrence. ✅ USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', 'What date is the next quarter moon?', or any question about UPCOMING phase dates. ❌ NOT FOR: 'What phase is the moon in right now?' or 'What sign is the moon in?' → For the phase, sign and degree AT a moment, use ephemeris_moon_phase. CREDIT COST: 1-2 credits per occurrence returned — each occurrence takes one calendar search, plus a second search when the first window misses. So count=3 costs 3-6 credits. EXAMPLE: Find the next new moon: phase='new_moon' EXAMPLE: Find the next full moon after a specific date: phase='full_moon', after_date='2026-06-01' EXAMPLE: Find the next 3 full moons: phase='full_moon', count=3

ephemeris_next_lunar_phase

Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status for a single planet/body at a given date and time. 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: there is no South Node id. The South Node is always exactly opposite the North Node — request 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; that is correct. Id 11 is the analytical true node. Neither is a classical mean node. CREDIT COST: 1 credit per call. EXAMPLE: Where is Mars on 2026-03-20 at noon UTC? planet_id=4, datetime='2026-03-20T12:00:00Z'

ephemeris_planet_position

Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. Returns progressed planet positions, house cusps, aspects, and retrograde status. CREDIT COST: 1 credit per call. EXAMPLE: Secondary progressions for someone born 1985-06-21 at 2:00 PM in London, progressed to 2026-01-01: birth_datetime='1985-06-21T14:00:00', timezone='Europe/London', birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'

ephemeris_progressed_chart

Calculate a relocation chart — the same natal planetary positions re-cast for a different geographic location. Used to understand how living in a different city shifts house placements and angles, without changing the planetary longitudes in the chart. CREDIT COST: 1 credit per call. EXAMPLE: How does moving from Chicago to London change someone's chart? natal_datetime='1990-04-15T14:30:00', timezone='America/Chicago', natal_latitude=41.8781, natal_longitude=-87.6298, relocation_latitude=51.5074, relocation_longitude=-0.1278

ephemeris_relocation

Find all upcoming retrograde and direct stations for planets in a date range. Returns exact station times, longitudes, and signs. USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', 'What planets station this month?', 'When does Mars go direct?' ❌ NOT FOR: 'Is Mercury retrograde right now?' — that is the state at a single instant, so use ephemeris_retrograde_status (1 credit for one planet, vs 5 here). All required fields have smart defaults (searches the next 90 days from today). CREDIT COST: 5 credits per call. EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults): (no args required, will auto-scan next 90 days for all inner planets) EXAMPLE: Outer planet stations in 2026: start_date='2026-01-01', end_date='2026-12-31', planets='jupiter,saturn,uranus,neptune,pluto'

electional_station_tracker

Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station proximity. ✅ Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; 'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns retrograde or direct, or whether it stations anywhere in a date range, use electional_station_tracker. CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the all-planets sweep and costs 10 credits — the backend bills one credit per body and this fans out to 10. Only omit it when the question really is about every planet.

ephemeris_retrograde_status

Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude (happens once per year near the birthday). Returns the Solar Return chart for the year ahead. CREDIT COST: 5 credits per call. TARGET DATE: Provide target_datetime near the desired birthday year. If omitted, defaults to the current year's solar return. EXAMPLE: Solar return for someone born 1985-06-21 (current year): birth_datetime='1985-06-21T14:00:00Z' EXAMPLE: Solar return for 2027 specifically: birth_datetime='1985-06-21T14:00:00Z', target_datetime='2027-01-01T00:00:00Z'

ephemeris_solar_return

Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects (planetary connections between the two charts), composite points, and relationship indicators. Use this for compatibility analysis, relationship timing, or partnership insights. CREDIT COST: 3 credits per call. EXAMPLE: Compare two people's charts (local birth times, each with its zone): person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago', person_a_latitude=41.8781, person_a_longitude=-87.6298, person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles', person_b_latitude=34.0522, person_b_longitude=-118.2437

ephemeris_synastry

Resolve the IANA timezone for a latitude/longitude pair. Use when you have coordinates but need the timezone to interpret a local birth time. Pass `date` to also get the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call. If you are starting from a place name rather than coordinates, use location_search instead — it returns the timezone too, in the same single call.

timezone_resolve

Search for astrological transit events affecting a natal chart over a date range. Returns exact transit moments — when transiting planets form specified aspects to natal planet positions. EFFICIENCY TIP: Always specify both transiting_planets and natal_points to keep compute fast. Omitting both sends all outer planets against all core natal positions — a much heavier computation. ASPECT ANGLES: Use aspect_angle to search for specific aspects: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. Example: Saturn Return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0 Example: Uranus Opposition → transiting_planets=['uranus'], natal_points=['uranus'], aspect_angle=180 Example: Outer planets to natal Sun/Moon → transiting_planets=['saturn','uranus','neptune','pluto'], natal_points=['sun','moon'] DEFAULT natal_points (when omitted): sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: Explorer/PayG tier → 1 year max; Pro → 5 years; Startup → 10 years. CREDIT COST: 5 credits per call.

ephemeris_transits

Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements in rashis (sidereal signs), nakshatras with pada, navamsa placements, and bhavas (houses). Uses Whole Sign houses, sidereal zodiac with configurable ayanamsa. CREDIT COST: 1 credit per call. SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar EXAMPLE: Vedic chart for someone born Jan 15, 1990 at 8:30 AM UTC in Mumbai: datetime='1990-01-15T08:30:00Z', latitude=19.076, longitude=72.8777

vedic_chart