astro-mcp

Astrological MCP Server — high-precision astrology tools for LLM agents.

Implements 14 tools backed by Swiss Ephemeris (pyswisseph) and integrates with any Model Context Protocol client (Claude Desktop, etc.).

Runs locally over stdio or remotely over streamable HTTP — including as a claude.ai custom connector on the free plan:

New to claude.ai connectors? A step-by-step guide in Russian — connecting the free shared instance or deploying your own with one button, project setup and example prompts — lives at drewcyber.github.io/astro-mcp.

Tools

Related MCP server: auseklis

Installation

# 1. Clone
git clone https://github.com/DrewCyber/astro-mcp
cd astro-mcp

# 2. Create virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# 3. Install package + dev dependencies
pip install -e ".[dev]"

# 4. Download Swiss Ephemeris data files
bash scripts/download_ephe.sh

# 5. Set environment variable
export EPHE_PATH="$(pwd)/ephe"

# 6. Run tests
pytest tests/

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "astro": {
      "command": "/path/to/astro-mcp/.venv/bin/python",
      "args": ["-m", "astro_mcp"],
      "env": {
        "EPHE_PATH": "/path/to/astro-mcp/ephe",
        "GEOCODING_PROVIDER": "nominatim",
        "GEOCODING_USER_AGENT": "astro-mcp/1.0",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

Remote hosting (claude.ai and other web clients)

Free claude.ai accounts can connect one custom connector — a remote MCP server at a public HTTPS URL. Set ASTRO_MCP_TRANSPORT=http and the server exposes the same tools over stateless streamable HTTP at /mcp (plus /health for uptime pings):

export ASTRO_MCP_TRANSPORT=http
python -m astro_mcp    # serves http://127.0.0.1:8080/mcp

The fastest path is the Deploy to Render button above (free, no credit card). A prebuilt image is also published to GHCR on every release — docker run -d -p 8080:8080 ghcr.io/drewcyber/astro-mcp:latest serves http://localhost:8080/mcp with zero build steps. For a public shared instance, quick cloudflared tunnels, Google Cloud Run, Koyeb and troubleshooting, see DEPLOY.md.

Environment Variables

Architecture

src/astro_mcp/
├── server.py              # MCP server — tool registration and dispatch
├── schemas.py             # Pydantic input models (source of the JSON schemas)
├── config.py              # Settings from environment variables
├── core/
│   ├── models.py          # Data models and astrological constants
│   ├── errors.py          # AstroError and the structured error codes
│   ├── ephemeris_provider.py  # Swiss Ephemeris wrapper (pyswisseph)
│   ├── geocoding.py       # City → lat/lon/tz (geopy + timezonefinder)
│   ├── moon.py            # Lunar phase, lunations and void-of-course
│   └── formatters.py      # LLM-optimized serialization
└── tools/
    ├── natal.py           # Tool 1
    ├── transits.py        # Tool 2
    ├── progressions.py    # Tool 3
    ├── returns.py         # Tools 4 + 6
    ├── rectification.py   # Tool 5
    ├── synastry.py        # Tools 7 + 8
    ├── profections.py     # Tool 9
    ├── planetary_hours.py # Tool 10
    ├── arabic_parts.py    # Tool 11
    ├── ephemeris.py       # Tools 12 + 13
    └── antiscia.py        # Tool 14

Output Format

All tools return compact JSON without whitespace to minimise LLM context tokens (~75% smaller than verbose JSON). Planet codes are abbreviated (Su, Mo, Me, etc.), aspects use 3-letter codes (Cnj, Tri, Squ), and the retrograde flag ("R":true) is omitted when direct to save additional tokens.

Failures use the same contract, so a client never has to parse prose:

{"error":true,"code":"INPUT_ERROR","message":"Invalid arguments for 'calculate_natal_chart'.","hint":"birth_location.lat: Input should be less than or equal to 90"}

Planet Codes

Supported codes across tools:

• Su Sun

• Mo Moon

• Me Mercury

• Ve Venus

• Ma Mars

• Ju Jupiter

• Sa Saturn

• Ur Uranus

• Ne Neptune

• Pl Pluto

• Ch Chiron

• Li Black Moon Lilith (Mean Apogee)

• NN North Node (True Node by default; Mean Node when NODE_TYPE=mean)

• SN South Node

• Asteroids (where include_asteroids is supported): Ce Ceres, Pa Pallas, Jun Juno, Ves Vesta

Pass include_legend: true to calculate_natal_chart or calculate_transits to get a one-shot decoding dictionary for all codes. Aspect entries carry a sig field (0–1 significance: body weight × aspect weight × orb tightness); min_significance / top_n trim the lists, and degree_format defaults to "dec" ("dms" restores human-readable degree strings).

API Notes

• get_ephemeris accepts either a single planet or a list of planets.

• get_ephemeris.step supports 1h, 2h, 3h, 6h, 12h, 1d, 7d, 30d.

• get_ephemeris now returns a timezone field and formats dt in output_tz.

• find_aspect_exact_dates.mode supports:

  • transit-to-transit for two moving bodies

  • transit-to-natal for transit to a natal planet/angle

  • auto (default) infers mode from presence of birth_*

Testing

pytest tests/ -v --cov=src/astro_mcp --cov-report=term-missing

Golden-chart regressions live inline in the test suite (tests/test_audit_regressions.py) and were verified against Astro.com and Solar Fire.

License

MIT