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

Related MCP server: Vedaksha

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

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