# openephemeris

The most complete astronomical computation engine available as an MCP server. Open Ephemeris gives AI agents direct access to JPL DE440/DE441 ephemeris data — the same dataset used by NASA — for sub-…

## Quick Start

```bash
# Connect this server (installs CLI if needed)
npx -y @smithery/cli@latest mcp add open-ephemeris/openephemeris

# Browse available tools
npx -y @smithery/cli@latest tool list open-ephemeris/openephemeris

# Get full schema for a tool
npx -y @smithery/cli@latest tool get open-ephemeris/openephemeris explore_natal_chart

# Call a tool
npx -y @smithery/cli@latest tool call open-ephemeris/openephemeris explore_natal_chart '{}'
```

## Direct MCP Connection

Endpoint: `https://openephemeris--open-ephemeris.run.tools`

**Required config:**
- `apiKey` (header) — Your Open Ephemeris API key. Get a free one at openephemeris.com/dashboard

## Tools (57)

- `explore_natal_chart` — Generate an interactive natal chart wheel with clickable planets, houses, and aspects. Returns an embedded visual chart…
- `chart_wheel_on_planet_click` — Event handler called when the user clicks a planet in the interactive chart wheel. Provides rich contextual interpretat…
- `chart_wheel_on_house_click` — Event handler called when the user clicks a house cusp or house number in the chart wheel. Returns the astrological mea…
- `chart_wheel_on_aspect_click` — Event handler called when the user clicks an aspect line between planets in the chart wheel. Returns the astrological i…
- `chart_wheel_recalculate` — Recalculates the natal chart using a different house system. Called automatically by the chart wheel UI when the user s…
- `auth_login` — Start the device authorization flow to connect this MCP server to your OpenEphemeris account. Returns a verification UR…
- `auth_status` — Check the current authentication status of this MCP server. Shows whether the server is authenticated, which account it…
- `auth_logout` — Disconnect this MCP server from your OpenEphemeris account by clearing cached credentials. Does NOT revoke the API key …
- `dev_call` — Call any allowlisted Open Ephemeris API endpoint directly. This is the power-user escape hatch — use the typed tools (e…
- `dev_list_allowed` — List all API operations (method + path) that this MCP instance is authorized to call. Returns endpoint entries grouped …
- `ephemeris_natal_chart` — Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, aspects, and chart pattern…
- `ephemeris_transits` — Search for astrological transit events affecting a natal chart over a date range. Returns a list of exact transit momen…
- `ephemeris_moon_phase` — Get the Moon's current phase angle, illumination, and void-of-course status AT a specific point in time. Returns phase …
- `ephemeris_next_lunar_phase` — Find the next occurrence of a specific Moon phase after a given date. Returns the exact UTC datetime, zodiac sign, and …
- `ephemeris_next_eclipse` — Find the next solar or lunar eclipse. Returns the eclipse type, date/time of maximum, magnitude, and duration of totali…
- `human_design_chart` — Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type (Generator, Manifesting…
- `ephemeris_synastry` — Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects (planetary connections between th…
- `ephemeris_relocation` — Calculate a relocation chart — the same natal planetary positions re-cast for a different geographic location. Used to …
- `ephemeris_electional` — Find optimal planetary timing windows (electional astrology). Scans a date range to find the best times for an event ba…
- `electional_moment_analysis` — Analyze the astrological quality of a specific moment: planet positions, aspects, void of course status, lunar phase, d…
- `electional_station_tracker` — Find all upcoming retrograde and direct stations for planets in a date range. Returns exact station times, longitudes, …
- `electional_aspect_search` — Find all active aspects between planets at a specific moment. Returns aspect type, orb, quality score, and whether it's…
- `vedic_chart` — Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements in rashis (sidereal signs), …
- `chinese_bazi` — Calculate a Chinese Ba Zi (Four Pillars of Destiny) chart. Returns the Year, Month, Day, and Hour pillars, each contain…
- `ephemeris_chart_wheel` — Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel …
- `ephemeris_bi_wheel` — Generate a Bi-Wheel (Synastry/Transit) image (SVG) comparing two charts. Draws Subject A's planets on the inside wheel …
- `ephemeris_solar_return` — Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude (happens once per yea…
- `ephemeris_lunar_return` — Calculate the exact Lunar Return date/time — when the Moon returns to its natal ecliptic longitude (~every 27.3 days). …
- `ephemeris_planetary_return` — Calculate a planetary return — when any planet returns to its natal longitude. Useful for Jupiter returns (~12 years), …
- `ephemeris_progressed_chart` — Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. Advances the natal chart symbolically — 1 day = 1 yea…
- `ephemeris_planet_position` — Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status for a single planet/body at a give…
- `ephemeris_house_cusps` — Calculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location using one or more house system…
- `ephemeris_composite` — Calculate a composite chart from two or more natal charts. The composite uses midpoints of each planet pair to derive a…
- `ephemeris_composite_midpoint` — Calculate a midpoint composite chart — an alternative composite method using the midpoints of matching planet positions.
- `ephemeris_overlay` — Calculate an overlay chart — place one person's planets in another person's houses. Shows how person A's energies impac…
- `ephemeris_natal_transits` — Calculate active transits to a natal chart — shows which current planets are aspecting natal positions. Essential for p…
- `human_design_composite` — Calculate a Human Design composite chart for two people. Merges both bodygraphs to show shared channels, authority dyna…
- `human_design_penta` — Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional attributes, leadership dynamics, channels…
- `human_design_bodygraph` — Generate a Human Design Bodygraph image (SVG) from a birth datetime (UTC). Renders the full bodygraph circuit board sho…
- `hd_planetary_return` — Calculate a Human Design planetary return chart — full HD chart (type, strategy, authority, gates, channels) at the mom…
- `hd_opposition` — Calculate a Human Design opposition chart — the HD chart at the moment a planet opposes its natal position (180°).
- `ephemeris_natal_batch` — Calculate natal charts for multiple subjects in a single request. Supports up to 100 subjects. Returns enhanced natal c…
- `ephemeris_dignities` — Calculate essential dignities (domicile, exaltation, detriment, fall, peregrine) for all planets at a given date/time. …
- `ephemeris_retrograde_status` — Get retrograde/direct status and speed for all planets at a given date/time. Returns is_retrograde flag, longitude spee…
- `ephemeris_midpoints` — Calculate midpoints between all planet pairs for a given date/time and location. Returns midpoint longitude, the two pl…
- `ephemeris_fixed_stars` — Calculate positions of fixed stars and conjunctions to natal planets. Returns star longitude, magnitude, and any planet…
- `ephemeris_hermetic_lots` — Calculate Arabic Parts / Hermetic Lots (Lot of Fortune, Spirit, etc.) for a given chart.
- `ephemeris_angles_points` — Calculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, East Point, etc.) for a given date/time and loca…

---
*Response truncated. Use `npx -y @smithery/cli@latest` for complete data.*