Use this when the user asks 'make my natal chart', '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 — 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. The birthplace can be given as location (a place name — resolved server-side) or as coordinates, with the birth date, local time and zone.

CREDIT COST: 1 credit per call (+1 to resolve a place name).

Use this when the user asks 'what's my Human Design', 'am I a Generator / Projector / Manifestor / Reflector', 'show my bodygraph' or 'what's my strategy and authority'. Returns an interactive bodygraph (inline in Claude and ChatGPT; text summary elsewhere): centers, gates, channels, Type, Profile, Authority and Incarnation Cross, each clickable. Birthplace may be a place name (location).

CREDIT COST: 4 credits per call (2 chart + 2 render; +1 to resolve a place name). Human Design was originated by Ra Uru Hu; Open Ephemeris is an independent calculation service, not affiliated with Jovian Archive.

Use this when the user asks 'what are today's Human Design transits for me', 'what gates are being activated for me right now' or 'how is the current sky affecting my bodygraph'. Returns an interactive overlay bodygraph (inline in Claude and ChatGPT; text summary elsewhere) with the channels the transit completes and centers it defines, now or at a chosen datetime. Birthplace may be a place name (location).

CREDIT COST: 5 credits per call (chart 3 + render 2; +1 per place name). Human Design was originated by Ra Uru Hu; Open Ephemeris is an independent calculation service, not affiliated with Jovian Archive.

Use this when the user asks 'are we compatible in Human Design', 'what's our connection chart', 'what channels do we make together' or 'show our composite bodygraph' — two people's HD charts overlaid. Returns an interactive two-person overlay bodygraph (inline in Claude and ChatGPT; text summary elsewhere) with every connected channel classified by HD connection theory: electromagnetic (attraction), companionship (sameness), dominance (one defines), compromise (friction).

CREDIT COST: 5 credits per call (composite 3 + render 2). Human Design was originated by Ra Uru Hu; Open Ephemeris is an independent calculation service, not affiliated with Jovian Archive.

Use this when the user asks 'are we compatible', 'synastry with my partner', 'what's my horoscope for today', 'what's hitting my chart right now' or 'what's my solar return chart this year' — any two-ring comparison they should SEE — or 'our composite chart' / 'our Davison chart' for a couple's single relationship wheel. Returns an interactive bi-wheel (inline in Claude and ChatGPT; text summary elsewhere): inner wheel Person 1's natal chart, outer ring by mode — synastry (Person 2's natal; needs their birthplace), transit (a date; today for a daily horoscope), progressed, solar_arc (target date), solar_return (target year), lunar_return (target month) — with cross-aspects drawn and every planet, aspect line and cusp clickable. composite and davison instead return ONE wheel derived from both births (Person 2's birth datetime and birthplace required; composite is the midpoint method with no angles or houses, davison has real ones). Birthplaces may be place names (location, person2_location).

CREDIT COST: 2 credits per call for most modes (1 per wheel; +1 to resolve a place name); solar_return/lunar_return modes cost 6; composite/davison cost 3. house_system (placidus default; whole_sign) sets both rings' houses.

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): illumination, phase, Moon sign and degree, void-of-course timing, lunar age, days to the next New and Full Moon, and the tightest applying aspects.

CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).

Use this when the user asks 'what's happening in my chart this month', 'what transits are coming up for me', 'what does my year ahead look like', 'when will Saturn hit my chart' 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, natal point, aspect 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: searches run faster when transiting_planets and natal_points are given. MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400). CREDIT COST: 1 + span price: ≤1y 5 (6 total), ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70.

Use this when the user asks 'show my Vedic chart', 'my kundli', 'my Indian astrology chart', 'what's my nakshatra', 'my sidereal birth chart' or 'what's my lagna'. 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).

Use this when the user asks 'what element is the year of the Snake', 'what's the pillar, stem and branch or NaYin for my birth year' or 'what's the energy of this year' — a single-year lookup beyond the animal. Returns the year's Heavenly Stem, Earthly Branch, animal, element, polarity and NaYin for any year 1-9999.

CREDIT COST: 3 credits per call.

Use this when the user asks 'what's my BaZi', 'my Four Pillars', 'what's my Day Master', 'what's my Chinese zodiac animal and element' or 'my Chinese astrology chart'. 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).

Use this when the user asks to 'connect', 'sign in', 'log in' or 'link my Open Ephemeris account'. Returns a verification URL and code for the user to enter in their browser; the server then receives credentials automatically and every call is billed to that account (tier, credits, rate limits).

Use this when the user asks 'am I logged in', 'which account is this connected to', 'how am I authenticated' or 'when does my token expire'. Returns whether the server is authenticated, the linked account, the method (API key, JWT, device auth) and token expiry.

Use this when the user asks to 'log out', 'sign out', 'disconnect' or 'switch accounts' on this MCP server. Returns confirmation that cached device-auth credentials were cleared; an API key set in the environment is not revoked.

Use this when the user asks 'how many credits do I have left', 'what's my usage this month', 'what plan am I on' or 'how do I upgrade or top up'. Returns plan tier, billing period, credits used / included / remaining, API calls and subscription status with renewal date.

CREDIT COST: 0.

Use this when find_calculation returns a GET path (biodynamic days, tidal forcing, crescent visibility, catalogs). Returns the endpoint's JSON. Read-only; POST paths go to dev_write_api.

Target API: Open Ephemeris REST API (https://api.openephemeris.com), allowlisted paths only. format 'llm' = compact output. 4xx/5xx are refunded.

Use this when find_calculation returns a POST path (KP, Varshaphal, the Chinese calendar, bounds, eclipses on a chart). Returns the endpoint's JSON. Stateless compute; GET paths go to dev_read_api.

Target API: Open Ephemeris REST API (https://api.openephemeris.com), allowlisted paths only. format 'llm' = compact output. 4xx/5xx are refunded.

Use this when no typed tool fits, before dev_read_api or dev_write_api: KP or Varshaphal, the Chinese lunar calendar, bounds distributions, eclipses on a natal chart, Almuten or lunar mansions, Venus star points, batch charts. Searches the Open Ephemeris API catalog (https://api.openephemeris.com) by plain words and returns the best matches: path, which tool runs it, required inputs, an example request and the credit cost. Local, free, no API call.

Use this when the user wants their natal / birth chart 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) — and, on request, any of ~90 more bodies via additional_objects (Eris, Sedna, Psyche, Fortuna and so on) — angles (ASC/MC/DSC/IC), house cusps, retrograde flags and the major aspect grid; format='llm' gives compact output. Takes coordinates, not a place name.

CREDIT COST: 1 credit per call.

Use this when the user asks 'when is my Saturn return', 'when does Pluto square my Sun', 'what transits do I have this month or next year', 'my biggest transits this 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; sort=significance adds ranked, the hits scored biggest first.

ASPECT ANGLES (aspect_angle): 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. Saturn return → transiting_planets=['saturn'], natal_points=['saturn']. Default transiting_planets and natal_points: sun through saturn; naming fewer is faster. 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, with the resume point in truncation.resume_from.

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.

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 time of each upcoming occurrence of the phase.

CREDIT COST: 2 credits per occurrence; count max 12.

Use this when the user asks 'when is the next eclipse', 'when is the next solar / lunar eclipse' or 'is there an eclipse visible from Tokyo'. Returns the eclipse type, time of maximum, magnitude and totality duration; with latitude+longitude, local contact times and visibility.

CREDIT COST: 1 credit per call.

Use this when the Human Design chart is wanted as data — 'give me my HD activations', 'what are my variables', 'my Human Design chart as JSON'. Returns Type, Strategy, Authority, Profile, Centers, Gates, Channels, Incarnation Cross, and Personality and Design planetary positions.

CREDIT COST: 2 credits per call.

Takes coordinates, not a place name.

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.

Use this when the user asks 'how does my chart change if I move to London', 'what's my chart in Paris', '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.

Use this when the user asks 'is today a good day to …', 'what's the sky like 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.

Use this when the user asks 'when does Mercury go retrograde', 'when does Mercury retrograde end', 'when does Pluto go direct' or 'Mercury retrograde dates for 2026'. Returns every retrograde and direct station, Mercury through Pluto, with time, longitude and sign; default the next 90 days, max one year.

CREDIT COST: 5 credits per call.

Use this when the Vedic / Jyotish chart is wanted as data — 'my sidereal placements as JSON', 'nakshatra and pada for every planet', 'my navamsa positions', 'what's my current dasha', 'today's panchang'. Takes coordinates, not a place name. Returns sidereal planet placements in rashis, nakshatras with pada, navamsa placements and bhavas (Whole Sign houses), with Ketu; optional Vimshottari dasha and divisional charts (vargas), or the day's panchang.

CREDIT COST: 1 credit per call.

Use this when the user asks 'when exactly is my solar return', 'my birthday chart for this year' 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.

Use this when the user asks 'what's my progressed chart', 'my secondary progressions', 'where is my progressed Moon right now' 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, tertiary or minor; converse counts backward.

CREDIT COST: 1 credit per call.

Use this when the user asks for 'zodiacal releasing', 'loosing of the bond', 'my annual profections', 'who is my time lord this year' or 'my firdaria'. Returns Hellenistic time-lord periods over a date window: zodiacal releasing levels 1–2 with peak and loosing-of-the-bond flags, the profection year with house and lord, optional firdaria, and each change date.

CREDIT COST: 5 credits for releasing from one Lot plus profections (1 natal + 2 + 2); 2 more per extra Lot or firdaria.

Use this when the user asks 'where is Mars right now', 'what sign is the Moon in today', 'what's my sun sign / star sign' (planet_id=0; a bare birth date resolves to noon UTC, no location needed), 'where was Jupiter on my birthday', 'where is the North Node' — one body at one moment. 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. NODES: id 10 is the mean North Node (mean-node polynomial); id 11 is the true North Node (osculating, referenced to the true ecliptic of date). There is no South Node id; the South Node longitude is a North Node longitude plus 180° (mod 360).

CREDIT COST: 1 credit per call.

Use this when the user asks 'what are my house cusps', 'which sign is my 7th house', 'what's my Midheaven', 'show my houses in Whole Sign' or 'compare Placidus and Koch' — houses and angles only, for a date, time and place. Returns the twelve cusps and ASC/MC/DSC/IC for each requested system.

HOUSE SYSTEM CODES: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign.

CREDIT COST: 1 credit per call.

Use this when the user asks 'is Mercury retrograde right now', 'was Mars retrograde when I was born' or 'which planets are retrograde at the moment'. Returns is_retrograde, speed and station proximity for one planet (Mercury is planet_id=2) or all ten.

CREDIT COST: 1 credit per planet (10 for all).

Use this when the user asks 'where is my Vertex', 'what's my East Point / equatorial ascendant' or 'what are my chart angles' for a date, time and place. Returns ASC, MC, DSC, IC, Vertex and the Equatorial Ascendant/Descendant (also as east_point).

CREDIT COST: 1 credit per call.

Use this when the user asks 'is 15° Aries square 18° Cancer', 'how many degrees apart are my Sun and Moon' or 'is this within orb'. Returns the separation between two ecliptic longitudes and any aspect within orb.

CREDIT COST: 1 credit per call.

Use this when the user asks 'show my astrocartography map', 'where are my Jupiter lines' or wants the whole-world list of their lines. Returns each planet's MC, IC, AC and DC lines with sign and equator-crossing longitude (no map geometry).

CREDIT COST: 10 credits per call. Pro tier.

Use this when the user asks 'is Tokyo good for me', 'where should I live according to my chart' or 'should I move to Austin'. Returns every astrocartography line (power and aspect lines) within radius_deg of a place, nearest first.

CREDIT COST: 10 credits per call. Pro tier.

Use this when the user asks 'when does Saturn enter Aries', 'when does Mercury change signs', 'when is the Moon in Scorpio next', or when a planet reaches an exact degree. Returns each sign ingress (exact UTC time, signs left and entered, retrograde flag) or, with degree, each crossing of that longitude.

CREDIT COST: 5 credits; 1 when the only planet is the Moon (90 days at most).

Use this when the user asks 'when does transiting Saturn enter my gate 34' or 'when do I get channel 20-34 from transits'. Returns each gate entry and exit over a range; with birth data or natal_gates, when a transit completes one of the person's channels.

CREDIT COST: up to 1 year 5, 3 years 10, 5 years 15. Explorer plans: 1 year at most.

Use this when the user gives a birth city, hometown or any place name — 'born in Chicago', 'Mumbai, India', 'what timezone was Paris in 1985' — and a chart needs coordinates and a timezone. Returns display name, region (state/province), latitude, longitude and IANA timezone. With the birth date as date it also returns 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. The result is flagged ambiguous when several places share the name (e.g. "portland"). A trailing "City, ST" qualifier in the query is honored. CREDIT COST: 1 credit per call.

Use this when the user asks 'what timezone is this location in' or 'what was the UTC offset there on that date', or coordinates are known and the IANA zone is needed for a local birth time. Returns the IANA zone and, with date, the historical UTC offset. CREDIT COST: 1 credit per call.