🌌 Astro Skill

🎯 Overview

Astro Skill is a production-grade, deterministic Vedic astrology engine that converts birth details and celestial coordinates into structured mathematical charts, timelines, and factual reports.

🔬 Zero Hallucinations: 100% calculation-backed using bundled Swiss Ephemeris data (.se1 SWIEPH via pyswisseph) and Lahiri (Chitrapaksha) ayanamsa.
🔌 3 Plug-and-Play Surfaces:
1. Stdio MCP Server (astro-mcp): 11 stable tools for Claude Desktop, Cursor, Codex, OpenClaw, and any Model Context Protocol client.
2. Python Library & CLI: Import directly in Python or run standalone CLI calculator scripts with --json outputs.
3. Agent Skill: Portable SKILL.md ready to equip autonomous coding agents and orchestrators.
📄 In-Process PDF Generator: Generates bilingual (Hindi & English) Kundali and Panchang charts via ReportLab with bundled Noto Sans Devanagari font — zero headless browser or Chrome dependencies.
🔒 100% Offline & Private: Zero external API keys, zero rate-limits, and zero network calls required for astrological calculations.

🏛️ Architecture & Layering

                     [ Client / Agent Request ]
                                 │
                 ┌───────────────┼───────────────┐
                 ▼               ▼               ▼
          Stdio MCP Server   Python CLI     Agent Skill
          (11 Tools/JSON)   (Scripts/Lib)   (SKILL.md)
                 │               │               │
                 └───────────────┬───────────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │   Astro Core Engine   │
                     │  (Swiss Ephemeris     │
                     │   + Lahiri Ayanamsa)  │
                     └───────────┬───────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
       [ Structured JSON ]            [ In-Process ReportLab PDF ]
       - 12 Bhavas, Grahas, Yogas     - Lagna & Navamsa (D1/D9)
       - Vimshottari Timeline         - Devanagari Hindi/English
       - Gochar & Guna Milan          - Dasha Strips & Panchang

✨ Core Capabilities

Category	Features & Astrological Foundations
Kundali (D1 & D9)	Lagna, Rashi, Nakshatra + Pada, 9 Grahas with true retrograde flags, whole-sign houses, and high-precision Navamsa (D9) divisional chart.
Planetary Strengths	Classical dignity, Digbala, Vargottama, Combustion (Asta), Graha Yuddha, and Lagna-specific functional benefic / malefic classifications.
Classical Yogas	Gajakesari, Budhaditya, Pancha Mahapurusha, Raja Yogas, Neechabhanga, Vipreet (Harsha/Sarala/Vimala), Kaal Sarp (full/partial), Parivartana (Maha/Khala/Dainya) — with classical cancellation checks.
12-House Bhava Analysis	House lords with placement & strength, occupants, Parashari planetary aspects (Drishti), and Bhava Karakas.
Vimshottari Dasha	Mahadasha, Antardasha, and Pratyantardasha timelines with true astronomical birth-balance handling.
Daily Panchang	Sunrise-anchored Tithi, Vara, Nakshatra, Yoga, Karana, Sunrise/Sunset, auspicious Muhurtas, and Anandadi/Amrit yogas.
Gochar (Transits)	Real-time planetary transits mapped against natal Moon and Lagna, with retrograde indicators and Saturn Sade Sati tracking.
Guna Milan (Matchmaking)	Complete 36-point Ashtakoot compatibility scoring with Nadi, Bhakoot, Gana, and Mangalik Dosha analysis.
Classical Remedies	Prioritized mantras, gemstones, fasting days, daan (charity), and rituals in bilingual Hindi/English.

🚀 Quick Start

1. Install from PyPI

pip install astro-skill

Requires Python 3.11+.

2. Run the Stdio MCP Server

astro-mcp
# or: python -m services.astro_mcp

3. CLI Command Examples

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

# Calculate Vimshottari Dasha Timeline
python -m astro.scripts.dasha_calculator --kundali-json chart.json --json

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

# Ashtakoot Guna Milan (Compatibility)
python -m astro.scripts.guna_milan --kundali-a-json person_a.json --kundali-b-json person_b.json --json

# Generate Factual Bilingual PDF Report
python -m astro.scripts.pdf_report --kundali-json chart.json --dasha-json dasha.json \
  --panchang-json panchang.json --output report.pdf --language hi

4. Python Library Usage

from astro.scripts.kundali_calculator import calculate_kundali

kundali = calculate_kundali(
    dob="15/08/1990",
    tob="14:30",
    place="Mumbai",
    lat=19.0760,
    lon=72.8777,
    tz_str="Asia/Kolkata"
)

print(f"Lagna: {kundali['lagna']['sign_name']}, Nakshatra: {kundali['nakshatra']['name']}")

🤖 MCP Server Setup

The built-in MCP server exposes 11 tools over stdio. It includes SQLite client profile management and report generation out of the box.

📋 Available MCP Tools (11)

Tool Name	Description
`parse_birth_details`	Parse conversational birth-detail strings into structured ISO date/time and coordinates.
`save_client_profile`	Upsert client profile and birth parameters into local SQLite database.
`find_client_profile`	Search client by `client_id` or name substring.
`list_client_reports`	Retrieve previously generated reports for a client.
`calculate_kundali`	Compute complete Lahiri/whole-sign Kundali, Navamsa (D9), yogas, and bhava data.
`calculate_dasha`	Compute Vimshottari Mahadasha + Antardasha timeline with exact birth balance.
`calculate_gochar`	Compute transit chart and Sade Sati status for any target date.
`calculate_compatibility`	36-point Ashtakoot Guna Milan compatibility score between two charts.
`calculate_panchang`	Daily sunrise-anchored Panchang (Tithi, Vara, Nakshatra, Yoga, Karana).
`generate_report_json`	Compile an all-in-one structured astrology draft JSON.
`generate_pdf_report`	Render a clean, printable PDF report using in-process ReportLab.

⚙️ Client Configurations

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "astro": {
      "command": "astro-mcp"
    }
  }
}

Cursor (`settings.json` / MCP Config)

{
  "mcpServers": {
    "astro": {
      "command": "python",
      "args": ["-m", "services.astro_mcp"],
      "cwd": "C:/path/to/astro-skill"
    }
  }
}

👑 Pro Report Tier

This repository contains the open-core deterministic engine — mathematical calculations, structured JSON schemas, and factual ReportLab PDFs.

For astrologers, consultancies, and consumer apps seeking client-ready, beautifully designed Janma Patrikas, a Pro Report Tier is available:

📖 Pandit-Grade LLM Synthesis: Deep house-by-house, dasha-by-dasha, and transit narrative analysis in Hindi, English, or Hinglish.
🎨 Premium Print-Ready Layout: Multi-page styled Janma Patrika with rich cover pages, divisional charts, and branded styling.
⚡ Prioritized Actionable Remedies: Context-aware Gemstone, Mantra, Yantra, and Daan suggestions tailored to running dasha periods.

📩 Interested in licensing the Pro Tier or API? Contact: adityaryawork@gmail.com

🛠️ Development & Testing

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

# Run full test suite (154 tests)
pytest -q

# Linter & format check
ruff check astro services scripts

🛡️ Safety Boundaries

Calculation-Backed Drafts: Reports are mathematical baselines intended for review by an astrologer or operator before sharing.
Missing Birth Details: Never guess or synthesize birth times or locations; prompt the user if inputs are missing.
Ethical Guardrails: Strictly prohibits generating fatalistic claims, death timing, medical diagnoses, or unavoidable harm predictions.

Astro Skill MCP Server

🌌 Astro Skill

🎯 Overview

🏛️ Architecture & Layering

✨ Core Capabilities

🚀 Quick Start

1. Install from PyPI

2. Run the Stdio MCP Server

3. CLI Command Examples

4. Python Library Usage

🤖 MCP Server Setup

📋 Available MCP Tools (11)

⚙️ Client Configurations

Claude Desktop (`claude_desktop_config.json`)

Cursor (`settings.json` / MCP Config)

👑 Pro Report Tier

🛠️ Development & Testing

🛡️ Safety Boundaries

📜 License

Latest Blog Posts

MCP directory API

🌌 Astro Skill

🎯 Overview

🏛️ Architecture & Layering

✨ Core Capabilities

🚀 Quick Start

1. Install from PyPI

2. Run the Stdio MCP Server

3. CLI Command Examples

4. Python Library Usage

🤖 MCP Server Setup

📋 Available MCP Tools (11)

⚙️ Client Configurations

Claude Desktop (claude_desktop_config.json)

Cursor (settings.json / MCP Config)

👑 Pro Report Tier

🛠️ Development & Testing

🛡️ Safety Boundaries

📜 License

Latest Blog Posts

MCP directory API

Claude Desktop (`claude_desktop_config.json`)

Cursor (`settings.json` / MCP Config)