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

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:

• RapidAPI (pay-as-you-go, credit card, instant): Ephemeris & Cosmic-Weather API on RapidAPI
• Direct: request a key at api.moonrituallibrary.com

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