{
  "markdown": "<!-- mcp-name: io.github.w8s/w8s-astro-mcp -->\n# w8s-astro-mcp\n\nPersonal astrological MCP server — natal charts, transits, forecasting, and relationship charts backed by a queryable SQLite database.\n\n[![Tests](https://github.com/w8s/w8s-astro-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/w8s/w8s-astro-mcp/actions/workflows/tests.yml)\n[![PyPI version](https://img.shields.io/pypi/v/w8s-astro-mcp)](https://pypi.org/project/w8s-astro-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/w8s-astro-mcp)](https://pypi.org/project/w8s-astro-mcp/)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n\n## Features\n\n- 🔭 **Swiss Ephemeris precision** — planetary positions via [pysweph](https://pypi.org/project/pysweph/); optional high-precision file download\n- 🗂️ **Multi-profile** — manage charts for yourself, family, and friends\n- 📜 **Persistent history** — every transit lookup auto-logged to SQLite; query by date, planet, or sign\n- 🔗 **Relationship charts** — composite and Davison charts for any group of 2+ people; place today's sky in any chart's house system\n- 🗓️ **Event & electional tools** — cast charts for any moment; scan windows for auspicious times\n\n## Quick Start\n\n**1. Install [uv](https://docs.astral.sh/uv/) if you don't have it** — see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for your platform.\n\n**2. Add to your Claude Desktop config:**\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"w8s-astro-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"w8s-astro-mcp\"]\n    }\n  }\n}\n```\n\n**3. Restart Claude Desktop, then create your profile:**\n\n> \"Create an astro profile for me — my name is [Name], born [YYYY-MM-DD] at [HH:MM] in [City, State].\"\n\n**4. Set yourself as the owner:**\n\n> \"Set me as the owner profile.\"\n\nThis 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).\n\n## Installation\n\n### Recommended: uvx (no install required)\n\n`uvx` pulls the package from PyPI and runs it in an isolated environment automatically. Use the config above.\n\n### Alternative: pip\n\n```bash\npip install w8s-astro-mcp\n```\n\nThen use `\"command\": \"w8s-astro-mcp\"` (no `args`) in your Claude Desktop config.\n\n### Upgrading from an earlier version\n\nIf you have an existing database from before v0.12, run the migration script once:\n\n```bash\npython scripts/migrate_owner_profile.py\n```\n\nThis renames the internal `current_profile_id` column to `owner_profile_id`. Safe to run multiple times.\n\n### Requirements\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) (for `uvx` method) or pip\n- Claude Desktop (or any MCP-compatible client)\n\n## Use Cases\n\n**Get started:**\n> \"Create an astro profile for me — my name is [Name], born [YYYY-MM-DD] at [HH:MM] in [City, State].\"\n\n> \"Show me my natal chart.\"\n\n**Daily practice:**\n> \"What are my transits for today?\"\n\n> \"When was Mercury last retrograde?\"\n\n> \"What major transits are coming up in the next 90 days?\"\n\n**Other profiles:**\n> \"Show me Liz's natal chart.\"\n\n> \"What are her transits today?\"\n\n> \"Compare my chart with Liz's.\" *(synastry)*\n\n**House placements:**\n> \"Where are today's planets in my natal houses?\"\n\n> \"Where does today's sky fall in our composite chart?\"\n\n**Relationships:**\n> \"Create a profile for my partner, born [YYYY-MM-DD] at [HH:MM] in [City, State].\"\n\n> \"Create a connection called 'Us' and show me our synastry.\"\n\n> \"Calculate a Davison chart for us.\"\n\n**Events & planning:**\n> \"Cast a chart for the moment we got married — [date] at [time] in [city].\"\n\n> \"Find auspicious times to sign a contract next month — Moon not void, Mercury direct.\"\n\n**History & research:**\n> \"When was Jupiter last in Taurus?\"\n\n> \"Show me all my transit lookups from last month.\"\n\n## Documentation\n\n| Doc | Contents |\n|-----|----------|\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Directory structure, full tool list, data flow, design decisions |\n| [docs/DATABASE_SCHEMA.md](docs/DATABASE_SCHEMA.md) | Full ERD, all models, example SQL queries |\n| [docs/ROADMAP.md](docs/ROADMAP.md) | Phase history and planned work |\n| [docs/TESTING_MCP.md](docs/TESTING_MCP.md) | How to configure Claude Desktop and smoke-test the server |\n\n## Contributing & Development\n\nSee [AGENTS.md](AGENTS.md) for the development workflow, testing commands, branch strategy, and release checklist.\n\n## Questions & Bugs\n\nOpen an issue on [GitHub](https://github.com/w8s/w8s-astro-mcp/issues).\n\n## License\n\n[AGPL-3.0](LICENSE)\n",
  "bytes": 4743,
  "sha": "40124b27d409fd2b3d2c3253847e81b15ea43261cce311af1c33c5e3a40b76c6",
  "repo_slug": "w8s/w8s-astro-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_w8s_w8s_astro_mcp_88b9954a/readme"
}