Open Ephemeris

The most complete astronomical computation engine available as an MCP server.

CommunityOnlineAPI key requiredGlobalFreeRead-only

What it can do

  • Explore Natal Chart: Generate an interactive natal chart wheel with clickable planets, houses, and aspects. Returns an embedded visual chart explorer that lets you click any planet, house, or aspect l
  • Explore Human Design: Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels. Returns an embedded visual bodygraph explorer that lets you click any center or gate f
  • Explore Bi Wheel: Generate an interactive bi-wheel chart comparing two astrological chart positions. The inner wheel is always Person 1's natal chart. The outer ring depends on mode: • synastry — Pers

What data it sees

Do you need an account

An API key from the service settings is required

The most complete astronomical computation engine available as an MCP server. Open Ephemeris gives AI agents direct access to NASA JPL DE440 ephemeris data — the same kernel used for spacecraft navigation — for sub-arcsecond planetary precision and zero hallucination on dates, degrees, and positions.

92 typed tools across every major astrological tradition: Western natal charts, transits, progressions, synastry, and composites; Human Design bodygraphs with gates, channels, and type analysis; Vedic/Jyotish with D-charts, dashas, and Ashtakavarga; Chinese BaZi Four Pillars; astrocartography power lines and local space; Venus Star Points; Arabic Parts; eclipse lookup; electional timing windows; and interactive chart apps (natal wheel, bi-wheel, bodygraph, moon phase) that render inline in hosts that support MCP Apps.

Also available as a one-click app in the ChatGPT app directory and as a custom connector for Claude. Free tier on sign-up, no card required.

Server tool list (60)

Raw names from tools/list. Only developers need these.

explore_natal_chartGenerate an interactive natal chart wheel with clickable planets, houses, and aspects. Returns an embedded visual chart explorer that lets you click any planet, house, or aspect line for instant astrological interpretation. Supports house system switching (Placidus, Whole Sign, Equal, Koch). The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. Use this instead of ephemeris_chart_wheel for a richer, interactive experience in MCP Apps-capable hosts (Claude Desktop). Falls back to static SVG in other hosts.
explore_human_designGenerate an interactive Human Design Bodygraph with clickable centers, gates, and channels. 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 for a rich, interactive HD experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.
explore_bi_wheelGenerate an interactive bi-wheel chart comparing two astrological chart positions. The inner wheel is always Person 1's natal chart. The outer ring depends on mode: • synastry — Person 2's natal chart (two-person compatibility). 1 credit. • transit — Transiting planets for a given date. 1 credit. • progressed — Secondary progressed positions (person2_datetime = target date). 1 credit. • solar_return — Nearest solar return chart (person2_datetime = year to return for). 5 credits. • lunar_return — Nearest lunar return chart (person2_datetime = target month). 5 credits. • solar_arc — Solar arc directed positions (person2_datetime = target date). 1 credit. Cross-aspects between both wheels are computed and displayed as coloured dashed lines. Click any planet, aspect line, or house cusp for interpretation.
bi_wheel_synopsisGenerate a master-astrologer-grade overview of the entire bi-wheel configuration — summarising the mode (synastry or transit), key cross-aspects by quality, dominant themes, stationing or slow-moving outer planet influences, and an interpretive narrative. Use this when the user asks for a full reading, a relationship overview, or a transit overview rather than clicking a specific element. Accepts the cross-aspect data from the chart payload.
explore_moon_phaseGenerate 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 Use this for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude Desktop). Falls back to a text summary in other hosts.
auth_loginStart the device authorization flow to connect this MCP server to your OpenEphemeris account. Returns a verification URL and code for the user to enter in their browser. The MCP server will then automatically receive credentials and all API calls will be linked to the user's account (tier, credits, rate limits). Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.
auth_statusCheck the current authentication status of this MCP server. Shows whether the server is authenticated, which account it's linked to, the authentication method (API key, JWT, device auth), and token expiry.
auth_logoutDisconnect this MCP server from your OpenEphemeris account by clearing cached credentials. Does NOT revoke the API key if one is set via environment variable — only clears device-auth cached credentials.
dev_callCall any allowlisted Open Ephemeris API endpoint directly. This is the power-user escape hatch — use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) first for common operations. Call dev_list_allowed to see all currently available endpoint paths. AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits. CREDIT COSTS: • Standard chart math (natal, progressed, bazi, vedic, iching): 1 credit • Human Design: 2 credits • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits • Comparative math (synastry, composite, overlay): 3 credits • Predictive ops (transits/search, returns): 5 credits • Predictive transit-chart: 1 credit • ACG / astrocartography: 10 credits (acg/hits: 15 credits) • Calendar endpoints: 10 credits • Catalog / metadata / health endpoints: 0 credits • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional) • format=llm (token-optimized output): available on all tiers COMMON CALLS: POST /ephemeris/natal-chart — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}}) POST /ephemeris/natal/batch — Up to 50 natal charts in one request POST /ephemeris/relocation — Relocated chart (same natal, new location) POST /predictive/transits/search — Transit event search over a date range POST /predictive/returns/solar — Solar return chart POST /predictive/returns/lunar — Lunar return chart POST /comparative/synastry — Two-person synastry chart POST /comparative/composite — Composite (midpoint) chart POST /human-design/chart — Full HD chart (body: {birth_datetime_utc: '1990-04-15T19:30:00Z'}) — lat/lon optional POST /time/julian-day — Convert date to JD (body: {year: 1987, month: 7, day: 15, hour: 14, minute: 1}) GET /ephemeris/moon/phase — Current/queried moon phase GET /ephemeris/moon/void-of-course — Next void-of-course period GET /ephemeris/agro/daily — Biodynamic farming day quality GET /ephemeris/agro/calendar — Multi-day biodynamic calendar GET /ephemeris/agro/void-of-course — Biodynamic VoC periods GET /eclipse/next-visible — Next eclipse visible from a location (query: lat, lon, type=solar|lunar) GET /eclipse/solar/global — Next global solar eclipse (query: date=YYYY-MM-DD) GET /eclipse/solar/local — Local solar eclipse (query: lat, lon) GET /tidal/forcing — Gravitational tidal forcing index POST /acg/power-lines — Astrocartography power lines (lat/lon GeoJSON) POST /acg/hits — ACG power at a specific location GET /calendar/astrology/moon-phases — Moon phase calendar for a date range GET /location/autocomplete — Geocode a place name (query: q=City Name) POST /timezone/lookup — Resolve timezone + UTC offset for a location POST /chinese/bazi — Chinese Ba Zi (Four Pillars) chart (body: {year, month, day, hour}) GET /chinese/zodiac — Chinese zodiac year element/animal POST /vedic/chart — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude}) GET /catalogs/bodies — List all supported celestial bodies BINARY RESPONSES: • Binary/image endpoints return {content_type, content_length, encoding, data_base64} so callers can decode bytes deterministically. ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints. format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for compact columnar output optimized for LLM token budgets (availability depends on your current plan).
dev_list_allowedList 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_call, 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 dev_call.
ephemeris_natal_chartCalculate 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. CREDIT COST: 1 credit per call. EXAMPLE: Calculate the natal chart for someone born April 15, 1990 at 2:30 PM in Chicago: datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298
ephemeris_transitsSearch 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; Developer → 5 years; Startup → 10 years. CREDIT COST: 6 credits per call.
ephemeris_moon_phaseGet the Moon's current phase angle, illumination, and void-of-course status AT a specific point in time. Returns phase name (New, Waxing Crescent, First Quarter, etc.), exact angle, illumination %, and next void-of-course period. ⚠️ THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' ❌ THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?' → For upcoming phase DATES use ephemeris_next_lunar_phase instead. CREDIT COST: 1 credit per call. If no datetime is provided, returns the current (live) moon phase. EXAMPLE: Get moon phase for a specific date/time: datetime='2026-03-20T12:00:00Z' EXAMPLE: Get the current moon phase right now: (call with no arguments)
ephemeris_next_lunar_phaseFind the next occurrence of a specific Moon phase after a given date. Returns the exact UTC datetime, zodiac sign, and degree. ✅ 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. CREDIT COST: 1 credit per call. 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_eclipseFind the next solar or lunar eclipse. Returns the eclipse type, date/time of maximum, magnitude, and duration of totality (if any). 📍 LOCATION OPTIONAL: • WITH latitude+longitude → returns local contact times and visibility for that specific location. • WITHOUT latitude+longitude → returns the next global eclipse of that type (no location needed). USE THIS TOOL FOR: 'When is the next solar eclipse?', 'When is the next total lunar eclipse?', 'Will there be an eclipse visible from Tokyo?' CREDIT COST: 1 credit per call. EXAMPLE: Next solar eclipse globally (no location needed): eclipse_type='solar' EXAMPLE: Next solar eclipse visible from New York: eclipse_type='solar', latitude=40.7128, longitude=-74.006 EXAMPLE: Next lunar eclipse from London: eclipse_type='lunar', latitude=51.5074, longitude=-0.1278
human_design_chartCalculate 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. 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. IMPORTANT: The datetime should be in UTC. If you have local birth time, convert to UTC first. EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 7:30 PM UTC: datetime='1990-04-15T19:30:00Z', latitude=41.8781, longitude=-87.6298
ephemeris_synastryCalculate 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: person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.8781, person_a_longitude=-87.6298, person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.0522, person_b_longitude=-118.2437
ephemeris_relocationCalculate 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', natal_latitude=41.8781, natal_longitude=-87.6298, relocation_latitude=51.5074, relocation_longitude=-0.1278
ephemeris_electionalFind optimal planetary timing windows (electional astrology). Scans a date range to find the best times for an event based on essential dignity, aspect quality, sect, and void-of-course moon penalties. Evaluates every hour and clusters the best continuous windows. CREDIT COST: 5 credits per call (heavy calculation). EXAMPLE: Find the best time to launch a business in early March 2026. start_date='2026-03-01', end_date='2026-03-10', latitude=40.7128, longitude=-74.0060, avoid_voc=true, lunar_phase='waxing'
electional_moment_analysisAnalyze the astrological quality of a specific moment: planet positions, aspects, void of course status, lunar phase, day ruler, and an overall electional score (0-100). Perfect for evaluating whether 'right now' or a specific date/time is good for action. CREDIT COST: 2 credits per call. EXAMPLE: Analyze March 21, 2026 at noon: date='2026-03-21T12:00:00'
electional_station_trackerFind 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?' All required fields have smart defaults (searches the next 90 days from today). CREDIT COST: 3 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_aspect_searchFind all active aspects between planets at a specific moment. Returns aspect type, orb, quality score, and whether it's applying or separating. Great for checking the 'weather' of a given day. CREDIT COST: 2 credits per call. EXAMPLE: What aspects are active on March 21, 2026? date='2026-03-21T12:00:00'
vedic_chartCalculate 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
chinese_baziCalculate a Chinese BaZi (四柱命盘 Four Pillars of Destiny) chart. Returns the Year, Month, Day, and Hour pillars, each with a Heavenly Stem (天干) and Earthly Branch (地支) pair. Includes the Day Master element and basic metadata. CREDIT COST: 1 credit (3 credits when include_visual=true). Set include_visual=true to receive a rendered SVG chart alongside the text data. For deep analysis, follow up with: • bazi_ten_gods() — Ten Gods (十神) per pillar including hidden stems • bazi_element_balance() — Weighted Wu Xing (五行) element scores + Yong Shen • bazi_luck_pillars() — 8 Da Yun 10-year luck cycles EXAMPLE: BaZi chart for someone born July 15, 1987 at 2 PM: year=1987, month=7, day=15, hour=14
bazi_ten_godsCalculate the Ten Gods (十神 Shí Shén) for a BaZi chart. Each of the 10 gods describes the relationship between the Day Master (日主, the person's core identity element) and every other Heavenly Stem in the chart — including visible stems and the hidden stems stored within each Earthly Branch. The 10 gods and their categories: COMPANION: Friend (比肩), Rob Wealth (劫财) OUTPUT: Eating God (食神), Hurting Officer (伤官) WEALTH: Indirect Wealth (偏财), Direct Wealth (正财) POWER: Seven Killings (七杀), Direct Officer (正官) RESOURCE: Indirect Resource (偏印), Direct Resource (正印) The Day Pillar itself has no Ten God (it IS the Day Master). Hidden stems in the Day Branch still receive Ten God labels. CREDIT COST: 1 credit (3 credits when include_visual=true). Set include_visual=true to receive an SVG Four Pillars chart alongside the Ten Gods data. EXAMPLE: Ten Gods for someone born July 15, 1987 at 2 PM: year=1987, month=7, day=15, hour=14
bazi_element_balanceCalculate the weighted Wu Xing (五行 Five Elements) distribution for a BaZi chart. Returns percentage scores for Wood, Fire, Earth, Metal, and Water across all chart positions. Scoring is weighted — hidden stems inside Earthly Branches count toward element totals: • Visible Heavenly Stems: 1.0 weight each (4 positions) • Hidden Stem main (本气): 1.0 weight • Hidden Stem secondary (中气): 0.6 weight • Hidden Stem residual (余气): 0.3 weight Also returns: • Day Master strength: 'strong' (旺, ≥50% own+resource elements) or 'weak' (弱) • Yong Shen (用神): the favorable element — what the chart needs most CREDIT COST: 1 credit (3 credits when include_visual=true). Set include_visual=true to receive an SVG Four Pillars chart alongside the element data. EXAMPLE: Element balance for 1987-07-15 at 14:00: year=1987, month=7, day=15, hour=14
bazi_luck_pillarsCalculate the 8 Da Yun (大运) 10-year luck pillar cycles for a BaZi chart. Luck pillars sequence through the sexagenary cycle starting from a person's 'starting age' (起运岁数), calculated by counting days from birth to the nearest solar term boundary (Jié 节). Each 3 days = 1 year of starting age (Zi Ping rule). Direction (forward/backward) depends on gender and year polarity: • Male in Yang year → forward • Male in Yin year → backward • Female in Yang year → backward • Female in Yin year → forward gender is REQUIRED — the direction of luck pillars is gender-dependent. Returns: starting_age, direction, direction_reason, and 8 pillars each with: stem, branch, Chinese characters, element, start_age, end_age CREDIT COST: 1 credit per call. EXAMPLE: Luck pillars for a female born July 15, 1987 at 2 PM: year=1987, month=7, day=15, hour=14, gender='female'
bazi_annual_pillarLook up the sexagenary pillar for any Gregorian year (1–9999). Returns the Heavenly Stem, Earthly Branch, Chinese characters, zodiac animal, element, polarity, and NaYin (纳音) poetic resonance image. NaYin maps each pair in the 60-cycle sexagenary sequence to one of 30 elemental images (e.g. '海中金 Metal in the Sea', '炉中火 Fire in the Furnace'). It is traditionally applied to the Year and Day pillars to reveal deeper elemental character. Use this to: • Identify the energetic quality of any given year • Determine a person's birth year pillar for compatibility context • Find the NaYin element for year or day interpretations CREDIT COST: 1 credit per call. EXAMPLE: Year pillar for 2025: year=2025
bazi_compatibilityCalculate BaZi compatibility between two people by comparing their Four Pillars charts. Returns a score 0–100, an assessment, and a breakdown of the harmony/clash/penalty factors found between the two charts. Scoring factors include: +5 Six Harmony (六合 Liù Hé) — branch pair bonds +8 Three Harmonies (三合 Sān Hé) — branch trinity formations -8 Six Clash (六冲 Liù Chōng) — opposing branch pairs -5 Six Harm (六害 Liù Hài) — branch interference pairs -6 Three Penalties (三刑 Sān Xíng) — branch penalty formations Assessment grades: 90–100: excellent | 70–89: good | 50–69: moderate | below 50: challenging CREDIT COST: 2 credits per call. EXAMPLE: Compatibility between two people: chart_a_year=1987, chart_a_month=7, chart_a_day=15, chart_a_hour=14 chart_b_year=1990, chart_b_month=3, chart_b_day=22, chart_b_hour=8
bazi_chartRender a self-contained SVG chart of a BaZi Four Pillars chart. Returns a production-quality visualization showing: • All four pillars (Year, Month, Day, Hour) with Heavenly Stems and Earthly Branches • Ten Gods (十神) labels for each non-Day pillar • Wu Xing (五行) element balance bar chart • Day Master identity with element and polarity The chart is rendered in the Open Ephemeris design system (OKLCH color tokens) and is fully self-contained — suitable for embedding or display without dependencies. Theme options: 'light' (default), 'dark', 'mono'. CREDIT COST: 3 credits per call (1 base + 2 visual render). Use this tool when the user asks to 'show', 'visualize', 'draw', or 'render' a BaZi / Four Pillars chart. For text-only data, use chinese_bazi() instead. EXAMPLE: Render a chart for someone born July 15, 1987 at 2 PM: year=1987, month=7, day=15, hour=14
ephemeris_chart_wheelGenerate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image that Claude displays inline in the conversation — no external tools needed. CREDIT COST: 2 credits per call. EXAMPLE: Generate a natal chart wheel for someone born April 15, 1990 in Chicago: datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298
ephemeris_bi_wheelGenerate a Bi-Wheel (Synastry/Transit) image (SVG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. Returns a native SVG that Claude displays inline in the conversation. CREDIT COST: 2 credits per call. EXAMPLE: Compare someone born April 15, 1990 (A) to someone born June 10, 1992 (B): datetime_a='...', latitude_a=..., longitude_a=..., datetime_b='...', latitude_b=..., longitude_b=...
ephemeris_solar_returnCalculate 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_lunar_returnCalculate the exact Lunar Return date/time — when the Moon returns to its natal ecliptic longitude (~every 27.3 days). Used to cast the monthly Lunar Return chart. CREDIT COST: 5 credits per call. TARGET DATE: Provide target_datetime near the month you want. If omitted, defaults to the next upcoming lunar return from today. EXAMPLE: Next lunar return after today for someone born 1990-04-15: birth_datetime='1990-04-15T14:30:00Z' EXAMPLE: Lunar return nearest March 2026: birth_datetime='1990-04-15T14:30:00Z', target_datetime='2026-03-15T00:00:00Z'
ephemeris_planetary_returnCalculate a planetary return — when any planet returns to its natal longitude. Useful for Jupiter returns (~12 years), Saturn returns (~29 years), Chiron returns (~50 years), Uranus returns (~84 years), etc. CREDIT COST: 5 credits per call. EXAMPLE: Saturn return for birth 1990-04-15 near year 2019: body='saturn', birth_datetime='1990-04-15T14:30:00Z', target_datetime='2019-01-01T00:00:00Z' EXAMPLE: Chiron return for birth 1975-03-10 near age 50: body='chiron', birth_datetime='1975-03-10T08:00:00Z', target_datetime='2025-01-01T00:00:00Z'
ephemeris_progressed_chartCalculate 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, progressed to 2026-01-01: birth_datetime='1985-06-21T14:00:00', birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'
ephemeris_planet_positionGet 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, 11=South Node, 12=Lilith, 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta. 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_house_cuspsCalculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location using one or more house systems. House system codes: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign. CREDIT COST: 1 credit per call. EXAMPLE: Placidus houses for London at 2026-03-20 noon UTC: datetime='2026-03-20T12:00:00Z', latitude=51.5074, longitude=-0.1278, house_systems=['P']
ephemeris_compositeCalculate a composite chart from two or more natal charts. The composite uses midpoints of each planet pair to derive a single relationship chart. CREDIT COST: 3 credits per call. EXAMPLE: Composite for two people: person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.88, person_a_longitude=-87.63, person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.05, person_b_longitude=-118.24
ephemeris_composite_midpointCalculate a midpoint composite chart — an alternative composite method using the midpoints of matching planet positions. CREDIT COST: 3 credits per call.
ephemeris_overlayCalculate an overlay chart — place one person's planets in another person's houses. Shows how person A's energies impact person B's life areas and vice versa. CREDIT COST: 3 credits per call.
ephemeris_natal_transitsCalculate active transits to a natal chart — shows which current planets are aspecting natal positions. Essential for predictive astrology. CREDIT COST: 3 credits per call. EXAMPLE: Current transits to someone born 1990-04-15: natal_datetime='1990-04-15T14:30:00', natal_latitude=41.88, natal_longitude=-87.63
human_design_compositeCalculate a Human Design composite chart for two people. Merges both bodygraphs to show shared channels, authority dynamics, and relationship type. CREDIT COST: 4 credits per call. EXAMPLE: person_a_datetime='1990-04-15T14:30:00Z', person_b_datetime='1988-09-22T08:15:00Z'
human_design_pentaCalculate a Human Design Penta (group) chart for 3-5 people. Shows functional attributes, leadership dynamics, channels, redundancies, and a group stability score. CREDIT COST: 6 credits per call. EXAMPLE (3 people): group_name='Team Alpha', members=[ {id: 'alice', name: 'Alice', datetime: '1990-04-15T14:30:00Z'}, {id: 'bob', name: 'Bob', datetime: '1988-09-22T08:15:00Z'}, {id: 'carol', name: 'Carol', datetime: '1995-01-10T11:00:00Z'} ]
human_design_bodygraphGenerate a Human Design Bodygraph image (SVG) from a birth datetime (UTC). Renders the full bodygraph circuit board showing all 9 centers, 36 channels, and 64 gates with Personality (conscious) and Design (unconscious) activations color-coded. Defined centers are filled with their HD doctrine color; open/undefined centers remain muted. Returns a native SVG that Claude displays inline. Use format='png' to opt into raster output (requires server-side rasterizer). CREDIT COST: 2 credits per call. EXAMPLE: Generate a bodygraph for someone born April 15, 1990 at 19:30 UTC: datetime='1990-04-15T19:30:00Z'
hd_planetary_returnCalculate a Human Design planetary return chart — full HD chart (type, strategy, authority, gates, channels) at the moment a planet returns to its natal position. Supports all HD-relevant planets. CREDIT COST: 2 credits per call. Key returns in Human Design: • Saturn Return (~29y, ~59y) — maturation/authority activation • Chiron Return (~50y) — wound-to-teaching integration • Jupiter Return (~12y) — expansion cycles • Mars Return (~2y) — energy/drive reset • Lunar Return (~27.3d) — emotional/body cycle EXAMPLE: Saturn return chart for birth 1990-04-15: planet='saturn', datetime='1990-04-15T19:30:00Z', return_year=2020
hd_oppositionCalculate a Human Design opposition chart — the HD chart at the moment a planet opposes its natal position (180°). Key oppositions in Human Design: • Uranus Opposition (~age 42) — midlife awakening/individuation • Saturn Opposition (~age 14-15, ~44) — structural tension • Jupiter Opposition (~age 6, ~18, ~30) — expansion challenges CREDIT COST: 2 credits per call. EXAMPLE: Uranus opposition for birth 1983-07-15: planet='uranus', datetime='1983-07-15T12:00:00Z', target_year=2025
ephemeris_natal_batchCalculate natal charts for multiple subjects in a single request. Supports up to 100 subjects. Returns enhanced natal chart data for each. CREDIT COST: 1 credit per subject. EXAMPLE: Two people batch: subjects: [ { name: 'Alice', datetime: '1990-04-15T14:30:00', latitude: 41.88, longitude: -87.63 }, { name: 'Bob', datetime: '1988-09-22T08:15:00', latitude: 34.05, longitude: -118.24 } ]
ephemeris_dignitiesCalculate essential dignities (domicile, exaltation, detriment, fall, peregrine) for all planets at a given date/time. Essential for traditional astrology. CREDIT COST: 1 credit per call.
ephemeris_retrograde_statusGet retrograde/direct status and speed for all planets at a given date/time. Returns is_retrograde flag, longitude speed, and station proximity for every planet. CREDIT COST: 1 credit per call. Optionally pass planet_id (0-9) to query a single planet.
ephemeris_midpointsCalculate midpoints between all planet pairs for a given date/time and location. Returns midpoint longitude, the two planets involved, and any planet at the midpoint. CREDIT COST: 1 credit per call.
ephemeris_fixed_starsCalculate positions of fixed stars and conjunctions to natal planets. Returns star longitude, magnitude, and any planets within orb. CREDIT COST: 1 credit per call.
ephemeris_hermetic_lotsCalculate Arabic Parts / Hermetic Lots (Lot of Fortune, Spirit, etc.) for a given chart. CREDIT COST: 1 credit per call.
ephemeris_angles_pointsCalculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, East Point, etc.) for a given date/time and location. CREDIT COST: 1 credit per call.
ephemeris_aspect_checkCheck the aspect between two ecliptic longitudes. Returns the angular separation and any aspects within orb (conjunction, sextile, square, trine, opposition, etc.). CREDIT COST: 1 credit per call. EXAMPLE: Check aspect between 15° Aries and 75° Gemini: longitude_1=15, longitude_2=75
venus_star_pointsGet Venus Star Points — the Sun-Venus conjunction events nearest to a birth date. Shows the quality of each conjunction (cazimi, combust, under beams) with zodiac details. CREDIT COST: 2 credits per call. EXAMPLE: Venus star points for someone born 1990-04-15: datetime='1990-04-15T14:30:00', latitude=41.88, longitude=-87.63
venus_star_points_conjunctionsFind all Sun-Venus conjunctions in a date range. Returns each conjunction with its exact timestamp, zodiac position, orb, visibility (morning/evening star), and dignity. CREDIT COST: 2 credits per call. EXAMPLE: Find Venus conjunctions in 2026: start_date='2026-01-01', end_date='2026-12-31'
venus_eight_year_starCompute the 8-year Venus Star pattern — the pentagram of 5 Venus-Sun conjunctions that trace a near-perfect star over 8 years (the Venus synodic cycle). Returns the 5 vertices with their zodiac positions. CREDIT COST: 2 credits per call. EXAMPLE: 8-year star starting from 2020: date='2020-01-01'
venus_phaseGet the current Venus phase — morning star, evening star, or combust. Returns Venus longitude, Sun longitude, elongation, retrograde/cazimi status. CREDIT COST: 1 credit per call. EXAMPLE: Venus phase right now (omit date): (no args required) EXAMPLE: Venus phase on a specific date: date='2026-03-20'
venus_elongationsFind Venus greatest elongation events (when Venus is farthest from the Sun in the sky). Returns east (evening star) and west (morning star) elongation peaks. CREDIT COST: 2 credits per call.