Astro Skill

Portable Vedic astrology engine, agent skill, and MCP server. Deterministic kundali, dasha, panchang, and yoga calculations with JSON and Hindi/English PDF reports — reusable by any agent or MCP-compatible client.

The repo is split so each layer can be reused on its own:

• astro/ — the portable skill: calculator scripts, reference data, bundled Swiss Ephemeris + Devanagari font, and tests. Drop it into any agent or call the scripts directly from Python.
• services/astro_mcp/ — a generic stdio MCP server exposing the same calculations plus SQLite storage as 11 stable tools.
• docs/ — architecture, roadmap, deployment, and operations docs.

Features

• Kundali — lagna, rashi, nakshatra + pada, nine grahas (with retrograde), whole-sign houses, and dosha flags (e.g. Mangalik with classical cancellation rules).
• Planetary strength flags — dignity, digbala, vargottama, combustion, graha yuddha, functional benefic/malefic per lagna, and a composite per-planet strength verdict.
• Yogas — Gajakesari, Budhaditya, Pancha Mahapurusha, Raja, Neechabhanga, Vipreet (Harsha/Sarala/Vimala), Kaal Sarp (full/partial), Parivartana (maha/khala/dainya), and more — with cancellation checks where classical.
• Full 12-house bhava data — house lords with placement + strength, occupants, Parashari aspects received, and bhava karakas, surfaced in the report JSON for downstream analysis.
• Gochar narrative — month-by-month (quarterly for long windows) transit sampling across the current antardasha window, with true per-date ephemeris recomputation.
• Remedies data — per-planet mantra/gemstone/fasting/daan/ritual reference (Hindi + English) with prioritization by planetary weakness and running dasha.
• Navamsa (D9) divisional chart in both JSON and the PDF report.
• Vimshottari dasha — mahadasha + antardasha timeline with correct birth-balance handling (the sub-period actually running at birth, not a fresh lord/lord cycle).
• Daily Panchang — tithi, vara, nakshatra, yoga, karana, sunrise/sunset — anchored at sunrise (classical convention), with muhurta and yoga detection.
• Lahiri (Chitrapaksha) sidereal positions, whole-sign houses.
• High precision — bundled Swiss Ephemeris .se1 data (SWIEPH) with an automatic Moshier fallback; each output records the tier used in calculation.ephemeris.
• Reports — structured JSON, and a factual PDF (birth summary, Lagna/Navamsa charts, planet table, dasha timeline, Panchang) via the in-process ReportLab renderer. Hindi/English, with a bundled Noto Sans Devanagari font.
• MCP server — 11 tools over stdio, with SQLite-backed client/report storage, input validation, and traversal-safe report filenames.

Pro report tier

This repo is the open engine — deterministic calculations, factual JSON, and a clean ReportLab PDF. On top of it there's a Pro report tier: an LLM-synthesized, pandit-grade Janma Patrika — bilingual narrative for every house, dasha and gochar; an honest chart-driven strength score; prioritized remedies; and a polished, print-ready design.

The engine here is deterministic and yours to build on. The Pro tier is a separate hosted/licensed layer aimed at astrologers and platforms who want a finished, client-ready report.

Want the Pro report tier for your product, practice, or platform? Reach out — adityaryawork@gmail.com.

Install (PyPI)

pip install astro-skill

# Run the stdio MCP server
astro-mcp
# or: python -m services.astro_mcp

Requires Python 3.11+. For development from source, use the editable install below.

Quick start (from source)

git clone https://github.com/adityarya24/astro-skill.git
cd astro-skill
python -m venv .venv && . .venv/bin/activate    # Windows: .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"

# Checks
python -m pytest -q
python -m ruff check astro services scripts

All tests pass. For OS-specific venv details and MCP client config examples, see docs/operations/install-smoke.md.

MCP server

services/astro_mcp/ is an importable package and a runnable stdio MCP server. The same TOOLS registry powers the unit tests and the wire protocol — no duplicated logic, and no environment variables required.

Tools (11): parse_birth_details, save_client_profile, find_client_profile, list_client_reports, calculate_kundali, calculate_dasha, calculate_gochar, calculate_compatibility, calculate_panchang, generate_report_json, generate_pdf_report.

python -m services.astro_mcp        # or `astro-mcp` after `pip install -e .`

Wire it into any MCP client (Claude Desktop, a Codex agent, or your own) by pointing the client's MCP config at that command with cwd set to the repo root. See services/astro_mcp/README.md for the tool contract and config examples, and verify an install in one shot with:

python scripts/smoke_mcp_client.py

Sample commands

# Kundali JSON
python astro/scripts/kundali_calculator.py --dob 26/12/2019 --tob 09:15 \
  --place Delhi --lat 28.6139 --lon 77.2090 --timezone Asia/Kolkata --json

# Panchang JSON
python astro/scripts/panchang_calculator.py --date 2026-05-21 \
  --place Delhi --lat 28.6139 --lon 77.209 --timezone Asia/Kolkata --json

# Hindi PDF (in-process ReportLab renderer)
python astro/scripts/pdf_report.py --kundali-json chart.json --dasha-json dasha.json \
  --panchang-json panchang.json --output report.pdf --language hi

Deployment

Run it as a Docker MCP server or straight from Python. The Dockerfile builds a slim image (Python, dependencies, Devanagari font, ephemeris data). See docs/deploy.md for build, run, smoke-test, and MCP-client wiring instructions.

Documentation

• docs/operations/install-smoke.md — fresh-clone install, MCP client config, smoke checklist.
• docs/deploy.md — Docker / MCP-client deployment.
• docs/architecture/generic-astro-platform.md — layering and reuse model.
• docs/architecture/astro-skill-roadmap.md — engine roadmap.
• services/astro_mcp/README.md — MCP server contract.
• astro/SKILL.md — agent skill instructions.

Production notes

• Positions use the bundled high-precision Swiss Ephemeris (SWIEPH) out of the box, not the lower-precision Moshier fallback.
• PDF rendering uses the in-process ReportLab backend — no browser dependency.
• Generated runtime data lives under an ignored data/ directory (or a caller-provided output directory).
• MCP tools validate their JSON schemas and keep generated filenames detached from caller-controlled identifiers.
• GitHub Actions runs install, tests, ruff, and skill validation on push and pull requests.

Safety boundaries

These rules apply across every layer and downstream product:

• Reports are calculation-backed drafts, intended for review by an astrologer or operator before any final reading is shared.
• Missing birth details must be requested rather than guessed.
• Approximate or partial inputs must be marked clearly in any output.
• Do not generate death, accident, medical, or unavoidable-harm certainty predictions.

License

MIT — see LICENSE.