Skip to main content
Glama
astro-cosmic-weather-mcp

astro-cosmic-weather-mcp

by ncreighton

astro-cosmic-weather-mcp

An MCP server that gives Claude (and any other MCP-compatible AI agent) live access to a real astronomical ephemeris — moon phases, zodiac transits, void-of-course windows, Mercury retrogrades, solstices/equinoxes, sabbats, natal moon placements, and a flagship combined "cosmic weather" feed.

Real Skyfield + JPL DE440s ephemeris data — not a hallucinated chart. Every number this server returns comes from an actual astronomical calculation or a fixed traditional calendar rule, computed server-side and served over a REST API. Claude never has to guess a moon phase or make up a retrograde date again.

This package is a client only — it makes authenticated HTTPS requests to the hosted API at https://api.moonrituallibrary.com. It contains no ephemeris code itself, so it's tiny, has almost no dependencies, and starts instantly.

Tools exposed

Tool

What it answers

cosmic_weather

"What's happening in the sky this week?" — flagship merged feed

moon_current

"What sign is the moon in right now?"

moon_phases

"When's the next full moon?"

moon_sign_ingresses

"When does the moon enter Scorpio?"

moon_void_of_course

"Is the moon void of course today?"

natal_moon

"What was my moon sign?" (given a birth date/time)

mercury_retrogrades

"When's the next Mercury retrograde?"

solar_terms

"When's the next equinox/solstice?"

sabbats

"When is Samhain this year?"

api_health

Diagnose connection issues

Related MCP server: Divine API Indian Astrology MCP

1. Get an API key

You need an API key before this server can return data (everything except the health check requires one). Two ways to get one:

Free tier is available on both paths — plenty of headroom for personal use inside Claude Desktop.

2. Install

Pick one:

# Recommended — no separate install step, uvx runs it on demand
uvx astro-cosmic-weather-mcp

# Or install it into your environment
pip install astro-cosmic-weather-mcp

# Or run from source
git clone https://github.com/moonrituallibrary/astro-cosmic-weather-mcp
cd astro-cosmic-weather-mcp
pip install -e .

3. Configure Claude Desktop

Open your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Add this to the mcpServers block (create the file/block if it doesn't exist yet), replacing YOUR_API_KEY_HERE with the key from step 1:

{
  "mcpServers": {
    "astro-cosmic-weather": {
      "command": "uvx",
      "args": ["astro-cosmic-weather-mcp"],
      "env": {
        "ASTRO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

If you installed via pip instead of uvx, use this form instead:

{
  "mcpServers": {
    "astro-cosmic-weather": {
      "command": "astro-mcp",
      "env": {
        "ASTRO_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Fully restart Claude Desktop (quit, don't just close the window) after editing the config. You should see a small tools/plug icon in the chat box indicating MCP tools are connected — "astro-cosmic-weather" will be listed with its 10 tools.

Optional: point at a different API base

If you're running your own instance of the underlying API (e.g. self-hosted, staging), add ASTRO_API_BASE to the same env block:

"env": {
  "ASTRO_API_KEY": "YOUR_API_KEY_HERE",
  "ASTRO_API_BASE": "https://your-own-host.example.com"
}

It defaults to https://api.moonrituallibrary.com if omitted.

4. Try it

Once connected, just ask Claude naturally — it will pick the right tool:

"What's the cosmic weather this week?" Claude calls cosmic_weather and gives you a chronological rundown of every moon phase, sign change, retrograde, and sabbat coming up in the next 7 days, plus a headline.

"What sign is the moon in right now?" Claude calls moon_current and tells you the live sign, phase, and illumination percentage.

"When is the next Mercury retrograde?" Claude calls mercury_retrogrades and reports the next upcoming window.

Other things worth asking: "When's the next full moon?", "Is the moon void of course today?", "When is Samhain this year?", "What was my moon sign — I was born March 21, 1994 in Chicago?"

Troubleshooting

Symptom

Fix

Tool replies "No ASTRO_API_KEY is configured"

Add/check the env.ASTRO_API_KEY value in your Claude Desktop config, then fully restart Claude Desktop.

Tool replies "Authentication failed (401)"

Your key is invalid, expired, or revoked — get a fresh one from the RapidAPI listing or api.moonrituallibrary.com.

Tool replies "Rate limit or monthly quota exceeded (429)"

You've hit your plan's request cap. Wait for the window to reset or upgrade your plan.

Tool doesn't show up in Claude Desktop at all

Check command/args are correct for how you installed it, and that the JSON in claude_desktop_config.json is valid (no trailing commas). Fully restart the app.

"Could not connect" / timeout errors

Run the api_health tool to check the service status, or visit https://api.moonrituallibrary.com/healthz in a browser.

Compliance

This server relays neutral astronomical and traditional-calendar facts only — moon phases, zodiac positions, retrograde windows, solstice/equinox timing, sabbat dates, illumination percentages. It never generates predictions, fortunes, compatibility scores, or claims about future events in a user's life. The underlying API enforces the same rule server-side.

For developers

Source layout:

mcp/
├── server.py          # the FastMCP server — one tool per API endpoint
├── pyproject.toml      # packaging (uvx / pip install)
├── requirements.txt    # plain pip deps (mcp, httpx)
├── README.md            # this file
└── PUBLISHING.md        # registry/discovery listing notes

Run locally without installing:

pip install -r requirements.txt
set ASTRO_API_KEY=your_key_here   # Windows (cmd)
$env:ASTRO_API_KEY="your_key_here" # Windows (PowerShell)
export ASTRO_API_KEY=your_key_here # macOS/Linux
python server.py

The server speaks MCP over stdio, so it expects to be driven by an MCP client (Claude Desktop, the mcp CLI inspector, etc.) rather than run interactively.

License

MIT

Available Tools

10 tools
api_healthA

Check whether the Ephemeris & Cosmic-Weather API is currently reachable and healthy. Use this to diagnose connection problems before assuming a specific data tool is broken — e.g. if another tool call fails with a connection or timeout error, call this first to confirm whether the issue is the service being down versus something else. This endpoint requires no API key.

Inputs: no named parameters. Returns: object

cosmic_weatherA

FLAGSHIP tool: get a single merged, chronological "cosmic weather" feed combining every event type (moon phases, sign ingresses, void-of-course windows, Mercury retrogrades, solar terms, sabbats) for the next N days, plus a human-readable headline summarizing the period. Use this as the default/first tool when the user asks broad questions like "what's the cosmic weather this week?", "what's happening in the sky today?", "give me an astrology overview for the next few days", or anything that isn't obviously scoped to just one event type — it's the richest single call and usually answers the question without needing any other tool.

Args: days: How many days ahead to include, starting from now. Defaults to 7. Use larger values (e.g. 30) for "this month" style questions. tz: IANA timezone name for event timestamps and local-time labeling. Defaults to "UTC".

Inputs: tz, days. Returns: object

mercury_retrogradesA

List Mercury retrograde windows (paired start/end dates) within a date range. Use this when the user asks "when is the next Mercury retrograde?", "is Mercury retrograde right now?", or wants a schedule of upcoming retrograde periods. If no range is given, the API defaults to now through +90 days — for "is it retrograde right now" pass a range that starts before today.

Args: from_date: Start of the range, ISO 8601 (e.g. "2026-01-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-12-31"). Omit for "90 days from the start".

Inputs: to_date, from_date. Returns: object

moon_currentA

Get the Moon's CURRENT (right-now) position and phase: zodiac sign, ecliptic longitude, phase name (e.g. "Waxing Gibbous"), and illumination percentage. Use this when the user asks "what sign is the moon in right now?", "what phase is the moon in today?", or "how full is the moon tonight?" — anything about the present moment, not a future/past date.

Args: tz: IANA timezone name for any timestamps in the response (e.g. "America/New_York", "Europe/London"). Defaults to "UTC".

Inputs: tz. Returns: object

moon_phasesA

List New Moon / First Quarter / Full Moon / Last Quarter events within a date range. Use this when the user asks "when is the next full moon?", "list the moon phases this month", or "when was the last new moon?". If no range is given, the API defaults to now through +90 days.

Args: from_date: Start of the range, ISO 8601 (e.g. "2026-08-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-11-01"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps and any local-time labeling. Defaults to "UTC".

Inputs: tz, to_date, from_date. Returns: object

moon_sign_ingressesA

List Moon zodiac sign ingress events (the exact moments the Moon moves from one zodiac sign into the next) within a date range. Use this when the user asks "when does the moon enter Scorpio?", "what sign is the moon moving into next?", or wants a schedule of moon-sign changes. If no range is given, the API defaults to now through +90 days.

Args: from_date: Start of the range, ISO 8601 (e.g. "2026-08-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-11-01"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps. Defaults to "UTC".

Inputs: tz, to_date, from_date. Returns: object

moon_void_of_courseA

List Void-of-Course Moon windows (periods between the Moon's last major aspect in a sign and its ingress into the next sign) within a date range. Use this when the user asks "when is the moon void of course this week?" or "is the moon VOC right now?". If no range is given, the API defaults to now through +90 days.

Args: from_date: Start of the range, ISO 8601 (e.g. "2026-08-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-11-01"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps. Defaults to "UTC".

Inputs: tz, to_date, from_date. Returns: object

natal_moonA

Compute the natal (birth) Moon placement for a specific birth date and time: Moon zodiac sign, Moon phase at that moment, and illumination percentage. Use this when the user asks "what was my moon sign?" or gives a specific birth date/time and wants their Moon placement. If the user only knows their birth date and not the exact time, use the default "12:00" and tell them the sign may be inexact if the Moon changed signs that day.

Args: date: Birth date, ISO 8601 (e.g. "1994-03-21"). Required. time: Birth time in 24-hour HH:MM format (e.g. "14:30"). Defaults to "12:00" (noon) if unknown. tz: IANA timezone name for the birth location at the time of birth (e.g. "America/Chicago"). Defaults to "UTC" — for an accurate result this should be the timezone that was in effect at the birth location and date, not the user's current timezone.

Inputs: date (required), tz, time. Returns: object

sabbatsA

List the Wheel of the Year sabbats (Samhain, Yule, Imbolc, Ostara, Beltane, Litha, Lughnasadh, Mabon) with their dates for a given year and hemisphere. Use this when the user asks "when is Samhain this year?", "list the sabbats for 2026", or asks about the pagan/wiccan wheel of the year. Southern hemisphere sabbat dates are offset by ~6 months from northern hemisphere ones (the seasonal correspondence flips).

Args: year: Calendar year (e.g. 2026). Omit to use the current year. hemisphere: Either "north" or "south". Defaults to "north".

Inputs: year, hemisphere. Returns: object

solar_termsA

List solstices, equinoxes, and cross-quarter days (the astronomical solar-year turning points) within a date range. Use this when the user asks "when is the next equinox?", "when does summer solstice happen this year?", or wants the solar calendar. If no range is given, the API defaults to now through +90 days.

Args: from_date: Start of the range, ISO 8601 (e.g. "2026-01-01"). Omit for "starting now". to_date: End of the range, ISO 8601 (e.g. "2026-12-31"). Omit for "90 days from the start". tz: IANA timezone name for the returned event timestamps. Defaults to "UTC".

Inputs: tz, to_date, from_date. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: current moon state, phase events, sign ingress events, void-of-course windows, natal computation, Mercury retrogrades, solar terms, sabbats, a merged feed, and health check. The flagship cosmic_weather tool is explicitly presented as an aggregation, reducing overlap.

    Naming Consistency4/5

    Tool names use a consistent lowercase snake_case style with descriptive noun phrases (moon_phases, solar_terms, sabbats). Minor inconsistency: natal_moon breaks the moon_ prefix pattern used by other moon tools, and there is no verb_noun pattern, but the naming is still predictable.

    Tool Count5/5

    10 tools is well-scoped for an astro-cosmic weather server, covering the moon, Mercury, solar terms, sabbats, and a combined feed. Each tool adds distinct value without redundancy.

    Completeness4/5

    The set covers current and natal moon states, future/past event lists, windows, retrogrades, solar terms, and sabbats, plus a health check. Gaps include lack of other planetary retrograde tools and no direct 'moon at date' tool, but inferring from ingresses is possible.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-contained MCP server that gives AI agents the ability to calculate high-precision astronomical data. It provides tropical zodiac coordinates, planetary speeds, retrograde detection, and house cusps using the trusted Swiss Ephemeris engine. 100%
      4
      AGPL 3.0
    • A
      license
      B
      quality
      B
      maintenance
      The MCP server for Divine API's Indian Astrology services, allowing AI assistants to query Vedic astrology data such as Panchang, Kundli, and matchmaking through natural language.
      131
      196 PyPI
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Astrology MCP server that computes natal charts, transits, synastry, progressions, returns, eclipses, retrogrades, and moon phases from a real ephemeris, enabling AI agents to provide accurate astrological calculations without hallucination.
      12
      75 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A custom MCP server providing tools for date/time, calculations, mock weather, and note management, enabling AI agents to perform these tasks via natural language.
      -