Retrograde MCP

Because your CI/CD pipeline deserves to know that Mercury is in retrograde.

A Model Context Protocol server that surfaces real astronomical data — planetary positions from the NASA JPL DE421 ephemeris and geomagnetic activity from NOAA SWPC — wrapped in the kind of rigorous astrological commentary your incident reports have been missing.

No fake planetary positions. No hardcoded retrograde dates. Every result is computed from actual ephemeris data at query time. If Mars suddenly goes rogue out of schedule, you WILL know.

• Retrograde MCP
  • What it does
    • Analysis methodology
  • Installation
    • Prerequisites
    • With uv (recommended)
    • With pip
    • From source
  • Claude Desktop configuration
    • Ephemeris cache location
  • Usage examples
  • Development
  • Data sources
  • Disclaimer

What it does

Analysis methodology

Planetary retrograde detection uses geocentric ecliptic longitude computed from the NASA JPL DE421 ephemeris (downloaded automatically via Skyfield). A planet is classified as:

• Retrograde when its ecliptic longitude is decreasing (speed < 0) and the absolute rate exceeds the planet's stationary threshold
• Stationary when the absolute rate of change falls below a per-planet threshold (the brief reversal period before/after retrograde) — thresholds follow professional-ephemeris convention: Mercury 0.083°/day, Venus 0.050°/day, Mars 0.025°/day, Jupiter/Saturn 0.017°/day, Uranus 0.006°/day, Neptune 0.003°/day
• Direct when its ecliptic longitude is increasing and the absolute rate exceeds the planet's stationary threshold

Lunar phase is computed from the angular separation between the Moon and the Sun in ecliptic coordinates, also from DE421.

Space weather (Kp-index) is fetched in real time from services.swpc.noaa.gov. The server tries the 1-minute feed first, falls back to the 3-hour consolidated product.

Cosmic risk score weights:

• Mercury and Mars retrograde: +20 each (critical infra/communication planets)
• Other retrograde planets: +10 each
• Stationary planets: +5 each
• Lunar phase: −10 to +20
• Kp-index: −5 to +50

Installation

Prerequisites

• Python 3.10+
• ~20 MB disk for the JPL ephemeris file (downloaded automatically on first run)
• Internet access for NOAA real-time Kp (gracefully degraded if unavailable)

With uv (recommended)

uvx retrograde-mcp

With pip

pip install retrograde-mcp
retrograde-mcp

From source

git clone https://github.com/Griboedow/Retrograde-MCP
cd Retrograde-MCP
pip install -e .
retrograde-mcp

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "retrograde": {
      "command": "retrograde-mcp"
    }
  }
}

Or with uvx:

{
  "mcpServers": {
    "retrograde": {
      "command": "uvx",
      "args": ["retrograde-mcp"]
    }
  }
}

Ephemeris cache location

The JPL DE421 file is cached to ~/.retrograde-mcp/ by default. Override with the RETROGRADE_CACHE_DIR environment variable:

{
  "mcpServers": {
    "retrograde": {
      "command": "retrograde-mcp",
      "env": {
        "RETROGRADE_CACHE_DIR": "/tmp/retrograde-cache"
      }
    }
  }
}

Usage examples

"Should I deploy right now?"

should_i_do_it get_cosmic_risk_score

Cosmic Risk Score: 🟠 ELEVATED (45/100)

Blocking factors:

• Geomagnetic storm (G1) in progress (Kp=5.7) — mental clarity across the team may be compromised

Caution factors:

• Full Moon 🌕 — maximum lunar intensity, not favorable for deployments

In your favor: Mercury, Mars, and Venus are all direct and supportive.

Recommendation: Hold off. Use get_favorable_window to find a better moment.

"Why did our API go down?"

explain_incident("API gateway returned 504s for 30 minutes starting at 14:00 UTC")

All planets are currently direct. The incident represents a triumph of purely human error, unassisted by celestial interference.

Contributing factors:

• Uranus (stationary at 58.51°) — disruption of unexpected outages, paradigm shifts, zero-day exploits
• Neptune (stationary at 1.94°) — unclear requirements, scope creep, ambient confusion
• Full Moon (98% illumination) — amplified cosmic instability
• Kp-index: 5.7 — G1 geomagnetic storm in progress

Remediation:

1. Document the incident with planetary positions recorded above
2. Schedule the post-mortem during a Mercury-direct period (you're clear — Mercury went direct on March 20)
3. Implement fixes during a waxing Moon phase for maximum cosmic support
4. Use retrograde_history to check if similar incidents correlate with the same planetary configurations

"When can I safely ship next?"

get_favorable_window · get_cosmic_risk_score

Next favorable window: April 19–29, 2026 — 11 days of cosmic cooperation with zero retrograde planets.

Today (April 3) scores 🟠 ELEVATED (45/100):

• Uranus & Neptune stationary (+10)
• Full Moon (+20)
• G1 geomagnetic storm, Kp=5.7 (+15)

No planets are retrograde, which is good — but the Full Moon and active geomagnetic storm push the risk up. If the release is ready and well-tested with solid rollback plans, today is survivable. If you can wait, April 19 is when the cosmos fully clear out for you.

"Give me the morning briefing"

get_daily_briefing

Cosmic Risk: MODERATE (27/100)

Stationary: Uranus, Neptune. Direct: Mercury, Venus, Mars, Jupiter, Saturn. Full Moon — 98% illumination. Kp-index: 1.7 — Quiet.

Proceed mindfully. Conditions are workable. Prioritize well-tested releases over experiments. Keep rollback procedures fresh.

"What was Mercury doing during our outages last months?"

retrograde_history

Mercury was retrograde from February 26 to March 20, 2026 — covering most of last month. That's 22 days where Mercury's apparent motion was reversed, which, according to the ephemeris data, means your March outages had a cosmically valid root cause.

The two other retrograde periods in the past year were: Jul 18 – Aug 11, 2025 (24 days) Nov 9 – Nov 29, 2025 (19 days)

If your outages clustered in early-to-mid March, they fell squarely within retrograde window #3. Cross-reference your incident log timestamps against Feb 26 – Mar 20 and you may find a suspicious overlap.

Development

pip install -e ".[dev]"
pytest

Data sources

Disclaimer

Planetary positions are computed from real astronomical data. The causal relationship between Mercury's ecliptic velocity and your deployment success rate has not been peer-reviewed. The author accepts no liability for outages, regressions, or existential crises arising from following or ignoring this advice.

That said: Mercury has been retrograde during a statistically suspicious number of incidents. We're just saying.