io.github.w8s/w8s-astro-mcp

Add a profile to an existing connection. Note: adding a member invalidates any cached charts for this connection.

Add a saved location (home, office, travel destination, etc.) for a profile. Every location must belong to a specific profile.

Cast an astrological chart for any date, time, and location. No profile required — useful for historical events, mundane astrology, and electional work. If 'label' is provided, the chart is saved to the database and can be referenced later via compare_charts using 'event:<label>'. If 'label' is omitted, the chart is calculated and returned but not saved.

Check the current ephemeris mode and precision level. Reports whether the built-in Moshier ephemeris (~1 arcminute) or Swiss Ephemeris data files (~0.001 arcsecond) are active, and shows the pysweph version.

Calculate aspects between two charts. Use for synastry (comparing two natal charts), transits (comparing natal chart with current positions), or event chart analysis. Finds conjunctions, oppositions, trines, squares, sextiles, and minor aspects. Each aspect names the chart each body belongs to (natal, transit, event) and, when a chart carries planet speeds (transit charts), whether the aspect is applying or separating with an estimated time of exactness. Times are UT. Transit-chart angles use the owner's current home location.

Create a new connection between two or more profiles for synastry or composite/Davison chart analysis. Requires at least 2 profile IDs. Use list_profiles to find profile IDs first.

Create a new astrological profile (for friends, family, synastry analysis, etc.). After creating, ask user if this should be their current profile. IMPORTANT: Ask for information conversationally: 1. Ask: 'What's their name?' 2. Ask: 'What's their birthday?' (get YYYY-MM-DD) 3. Ask: 'Do you know what time they were born? (If not, we can use 12:00)' 4. Ask: 'Where were they born?' (get city, state/country) Then look up coordinates and confirm before saving.

Delete a connection and all its cached charts. WARNING: Permanent and cannot be undone. Does not affect the member profiles themselves.

Delete a saved event chart by label. WARNING: Permanent and cannot be undone.

Delete a profile from the database. WARNING: This is permanent and cannot be undone. Deletes the profile and all associated natal chart data. If this is the owner profile, owner_profile_id will be set to NULL.

Stop the 'Data notice' about stored natal charts that need recalculating, until a different chart becomes affected. Call this ONLY when the user asks not to be reminded; it does not fix anything. Use undo=true to bring the notice back.

Download Swiss Ephemeris data files for higher-precision calculations. Upgrades from built-in Moshier ephemeris (~1 arcminute) to full Swiss Ephemeris files (~0.001 arcsecond). Downloads ~2 MB from the official Swiss Ephemeris GitHub repository to ~/.w8s-astro-mcp/ephe/. Use check_ephemeris first to see current precision mode.

Scan a time window and return candidate moments that satisfy electional astrology criteria. Useful for finding auspicious times to start a project, sign a contract, hold an event, etc. Scans at a configurable interval (default 60 minutes) and scores each moment against the requested criteria. Returns candidates ranked by score (most criteria met first), then by tightness. Maximum window: 90 days. Maximum interval: 360 minutes (6 hours). Minimum interval: 15 minutes. Available criteria: - moon_not_void: Moon is not void of course - no_retrograde_inner: Mercury and Venus are direct - no_retrograde_outer: Mars through Pluto are direct - no_retrograde_all: All planets are direct - moon_waxing: Moon is waxing (New to Full) - moon_waning: Moon is waning (Full to New) - benefic_angular: Venus or Jupiter in houses 1, 4, 7, or 10 - asc_not_late: Ascendant is not in the last 3° of its sign

Determine which house each planet occupies in a chart. Can use a natal chart (via profile_id or owner default) or a connection chart (composite/Davison via connection_id + chart_type) as the house reference frame. Shows both which planets are in each house and which house each planet is in.

Find the most recent logged transit where a planet met specific conditions. Examples: 'when was Mercury last retrograde?', 'when was the Moon last in Scorpio?', 'when was Mars last in my 7th house?'. Requires at least one of: sign, retrograde, or house.

Calculate (or retrieve cached) a composite or Davison chart for a connection. COMPOSITE: Each planet position is the circular mean of all members' natal positions. No swetest call needed — pure math on cached natal data. DAVISON: A real chart cast for the midpoint datetime and location of all members' births. Requires a swetest call. Birth times are converted to UTC before averaging, so timezone data in each profile's birth location is used. Results are cached in the database. Use invalidate=true to force recalculation.

Scan the ephemeris for upcoming or recent planetary sign ingresses and stations (retrograde/direct). Examples: 'what transits are coming up this month?', 'when does Mercury go retrograde?', 'show me major transits next April', 'what were the outer planet movements during the Renaissance?'. Use offset to shift the window from today. Use extended=true for historical or far-future windows (outer planets only).

Get the natal chart (birth chart) planetary positions for a profile. Defaults to the owner profile if no profile_id is supplied.

Query historical transit lookups stored in the database for a profile. Defaults to the owner profile. Supports filtering by date range, planet, and sign. Examples: 'show me last month\'s transits', 'when was Mercury in Capricorn?', 'what sign was Jupiter in last year?'

Get planetary transits for a specific date and location. Location can be a saved label ('home', 'work', 'birth'), or any city/place name ('Seattle', 'Bangkok, Thailand', 'Paris') — unknown names are geocoded automatically. Defaults to current home location if omitted.

List all connections with their member names and IDs. Use this to find connection IDs before requesting charts.

List all saved event charts. Shows label, date/time, location, and optional description. Saved charts can be used in compare_charts via 'event:<label>'.

List all astrological profiles in the database. Shows profile names, birth dates, and which is currently active. Use this to see all available profiles before creating, updating, or switching.

Remove a profile from a connection. Connection must retain at least 2 members. Note: removing a member invalidates any cached charts.

Remove a saved location. WARNING: Cannot remove locations that are set as birth locations for profiles.

Configure birth data and location for transit calculations. IMPORTANT: Ask the user for information conversationally in steps: 1. Ask: 'What's your birthday?' (get YYYY-MM-DD) 2. Ask: 'Do you know what time you were born? (If not, we can use 12:00)' (get HH:MM) 3. Ask: 'Where were you born?' (get city, state/country) Then look up coordinates and confirm with user before saving.

Set who you are — the human operating this server. This is a one-time setup step, not a session operation. The owner profile is the stable identity used as the default for get_natal_chart, get_transits, and all other tools when no profile_id is supplied. Use list_profiles to find your profile_id.

Update a profile field (name, birth date, birth time, etc.). Use with caution - changing birth data invalidates cached natal chart. Valid fields: name, birth_date, birth_time

View current astrological configuration (birth data and saved locations)

Generate a circular natal chart visualization and save to file. Creates a traditional astrological chart wheel with zodiac signs, houses, planets, and angles.