W8s Astro MCP server

<!-- mcp-name: io.github.w8s/w8s-astro-mcp -->

w8s-astro-mcp

Personal astrological MCP server — natal charts, transits, forecasting, and relationship charts backed by a queryable SQLite database.

⚠ Upgrading from v0.12 or earlier? Your stored charts were calculated with the wrong time zone. Birth, event and electional times were treated as UT instead of local time, so the Ascendant, MC, houses and Moon were off. Planet signs almost always stay the same. Run w8s-astro-recalculate --all to see what changes, then add --apply. Details

Features

• 🔭 Swiss Ephemeris precision — planetary positions via pysweph; optional high-precision file download
• 🗂️ Multi-profile — manage charts for yourself, family, and friends
• 📜 Persistent history — every transit lookup auto-logged to SQLite; query by date, planet, or sign
• 🧭 Transit reading — compare today's sky to your natal chart with applying/separating direction and an estimated time of exactness; opt-in JSON output
• 🔗 Relationship charts — composite and Davison charts for any group of 2+ people; place today's sky in any chart's house system
• 🗓️ Event & electional tools — cast charts for any moment; scan windows for auspicious times

Quick Start

1. Install uv if you don't have it — see the uv installation guide for your platform.

2. Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json
• Windows: %APPDATA%\Claude\claudedesktopconfig.json

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

3. Restart Claude Desktop, then create your profile:

"Create an astro profile for me — my name is [Name], born [YYYY-MM-DD] at [HH:MM] in [City, State]."

4. Set yourself as the owner:

"Set me as the owner profile."

This tells the server who you are. All tools default to your chart unless you ask about someone else. Everything is stored in ~/.w8s-astro-mcp/astro.db (macOS/Linux) or %USERPROFILE%\.w8s-astro-mcp\astro.db (Windows).

Installation

Recommended: uvx (no install required)

uvx pulls the package from PyPI and runs it in an isolated environment automatically. Use the config above.

Alternative: pip

pip install w8s-astro-mcp

Then use "command": "w8s-astro-mcp" (no args) in your Claude Desktop config.

Upgrading from an earlier version

If you have an existing database from before v0.12, run the migration script once:

python scripts/migrate_owner_profile.py

This renames the internal currentprofileid column to ownerprofileid. Safe to run multiple times.

Upgrading to v0.14.0 — recalculate your stored charts. Earlier versions used the local birth time as if it were UT, so every stored natal chart has the wrong Ascendant, MC, houses and Moon. Fix it once after upgrading:

w8s-astro-recalculate --all            # dry run: shows exactly what would change
w8s-astro-recalculate --all --apply    # backs up the database first, then recalculates
# with uvx: uvx --from w8s-astro-mcp w8s-astro-recalculate --all

Shortened. The full README is on GitHub.