# astro-cosmic-weather-mcp

An [MCP](https://modelcontextprotocol.io) 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](https://rapidapi.com/moonrituallibrary/api/ephemeris-cosmic-weather-api)
- **Direct**: request a key at [api.moonrituallibrary.com](https://api.moonrituallibrary.com)

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

## 2. Install

Pick one:

```bash
# 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:

```json
{
  "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:

```json
{
  "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:

```json
"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:

```bash
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