w8s-astro-mcp

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

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
• 🔗 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/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.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 current_profile_id column to owner_profile_id. Safe to run multiple times.

If a new install fails with AttributeError: 'Server' object has no attribute 'list_tools': upgrade to v0.12.1 or later (uvx --refresh w8s-astro-mcp, or pip install -U w8s-astro-mcp). Earlier versions did not limit which MCP SDK version they accept, so a new install picked up SDK 2.x, which this server does not support yet.

Requirements

• Python 3.10+
• uv (for uvx method) or pip
• Claude Desktop (or any MCP-compatible client)

Use Cases

Get started:

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

"Show me my natal chart."

Daily practice:

"What are my transits for today?"

"When was Mercury last retrograde?"

"What major transits are coming up in the next 90 days?"

Other profiles:

"Show me Liz's natal chart."

"What are her transits today?"

"Compare my chart with Liz's." (synastry)

House placements:

"Where are today's planets in my natal houses?"

"Where does today's sky fall in our composite chart?"

Relationships:

"Create a profile for my partner, born [YYYY-MM-DD] at [HH:MM] in [City, State]."

"Create a connection called 'Us' and show me our synastry."

"Calculate a Davison chart for us."

Events & planning:

"Cast a chart for the moment we got married — [date] at [time] in [city]."

"Find auspicious times to sign a contract next month — Moon not void, Mercury direct."

History & research:

"When was Jupiter last in Taurus?"

"Show me all my transit lookups from last month."

Documentation

Contributing & Development

See AGENTS.md for the development workflow, testing commands, branch strategy, and release checklist.

Questions & Bugs

Open an issue on GitHub.

License

AGPL-3.0