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
🗓️ Event & electional tools — cast charts for any moment; scan windows for auspicious times

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

2. Add to your Claude Desktop config:

{
  "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]."

That's it. Everything is stored in ~/.w8s-astro-mcp/astro.db (macOS/Linux) or %USERPROFILE%\.w8s-astro-mcp\astro.db (Windows).

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

pip install w8s-astro-mcp

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

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?"

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

Doc	Contents
docs/ARCHITECTURE.md	Directory structure, full tool list, data flow, design decisions
docs/DATABASE_SCHEMA.md	Full ERD, all models, example SQL queries
docs/ROADMAP.md	Phase history and planned work
docs/TESTING_MCP.md	How to configure Claude Desktop and smoke-test the server

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

Open an issue on GitHub.