astro-mcp

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.).

Tools

| # | Name | Description | |---|---|---| | 1 | calculate_natal_chart | Full natal chart: planets, angles, houses, aspects | | 2 | calculate_transits | Transit aspects to natal chart | | 3 | calculate_secondary_progressions | Day-for-a-year progressions + Solar Arc | | 4 | calculate_solar_return | Annual solar return chart | | 5 | calculate_rectification_hints | Score candidate birth times against life events | | 6 | calculate_lunar_return | Monthly lunar return chart(s) | | 7 | calculate_synastry | Cross-chart aspects + house overlays | | 8 | calculate_composite_chart | Midpoint or Davison composite chart | | 9 | calculate_profections | Annual profection — year lord and activated houses | | 10 | get_planetary_hours | 24 planetary hours for any day/location | | 11 | calculate_arabic_parts | 7 Arabic Parts (Fortune, Spirit, Marriage, etc.) | | 12 | get_ephemeris | Planet position table over a date range | | 13 | find_aspect_exact_dates | Find exact dates of a specific aspect | | 14 | calculate_antiscia | Antiscia and contra-antiscia points |

Installation

# 1. Clone
git clone https://github.com/your-org/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"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |---|---|---| | EPHE_PATH | ./ephe | Path to Swiss Ephemeris .se1 data files | | GEOCODING_PROVIDER | nominatim | nominatim or opencage | | OPENCAGE_API_KEY | — | Required if GEOCODING_PROVIDER=opencage | | GEOCODING_USER_AGENT | astro-mcp/1.0 | Nominatim user-agent | | GEOCODE_CACHE_SIZE | 512 | LRU cache size for geocoding results | | DEFAULT_HOUSE_SYSTEM | P | P=Placidus, W=Whole Sign, K=Koch | | DEFAULT_ORB_FACTOR | 1.0 | Global orb multiplier (0.5–1.5) | | LOG_LEVEL | WARNING | Python logging level |

Architecture

src/astro_mcp/
├── server.py              # MCP server — tool registration and dispatch
├── config.py              # Settings from environment variables
├── core/
│   ├── models.py          # Data models and astrological constants
│   ├── ephemeris_provider.py  # Swiss Ephemeris wrapper (pyswisseph)
│   ├── geocoding.py       # City → lat/lon/tz (geopy + timezonefinder)
│   └── 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.

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)
• SN South Node

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

Reference charts (tests/reference_data/) are verified against Astro.com and Solar Fire.

License

MIT