---

title: JyotishMCP emoji: 🪐 colorFrom: purple colorTo: indigo sdk: docker pinned: false

🔭 AstroConsultant — AI Astrology MCP Server

Professional-grade astrology API + MCP Server powered by Swiss Ephemeris (pyswisseph), supporting both Western (Tropical) and Vedic/Jyotish (Sidereal) traditions. Exposes 49 MCP tools and 70+ API endpoints for comprehensive astrological consultation.

┌──────────────────────────────────────────────────┐
│              Claude Desktop (UI)                 │
│                      │                           │
│              MCP Protocol (stdio)                │
│                      │                           │
│           ┌──────────▼──────────┐                │
│           │   MCP Server        │                │
│           │  (49 tools)         │                │
│           └──────────┬──────────┘                │
│                      │ HTTP/JSON                 │
│           ┌──────────▼──────────┐                │
│           │   FastAPI Backend   │                │
│           │   (10 routers,      │                │
│           │    70+ endpoints)   │                │
│           └──────────┬──────────┘                │
│                      │                           │
│           ┌──────────▼──────────┐                │
│           │  Swiss Ephemeris    │                │
│           │  (pyswisseph)       │                │
│           └─────────────────────┘                │
└──────────────────────────────────────────────────┘

---

✨ Features at a Glance

🕉️ Vedic / Jyotish (Sidereal)

Feature	Description
Kundli (Birth Chart)	Full sidereal chart with Whole Sign houses
Varga Charts (D1–D60)	16+ divisional charts (Navamsa, Dasamsa, etc.)
Dasha Systems	Vimshottari (Mahadasha → Sookshma), Yogini, Chara, Kalachakra
Current Dasha	Real-time Mahadasha / Antardasha / Pratyantardasha / Sookshma
Dasha Interpretation	AI-ready interpretation texts for any Dasha lord combination
Yogas	30+ classical yogas (Raja, Dhana, Viparita, Pancha Mahapurusha…)
Doshas	Mangal Dosha, Kala Sarpa Dosha detection
Shadbala	Six-fold planetary strength analysis
Ashtakavarga	Sarvashtakavarga + Bhinnashtakavarga + Transit Scoring
Sade Sati	Complete 100-year Sade Sati timeline with peak dates
Bhava Chalit	Sripati house system shifted-planet chart
Upagrahas	Mandi, Gulika, Dhooma, Vyatipata, Parivesha, Indrachapa, Upaketu
Jaimini System	Chara Karakas (AK–DK), Arudha Padas, Karakamsa
Lagna Lord Analysis	Ascendant lord placement, dignity, and interpretation
Gochar (Transit)	Vedic transit report based on natal Moon sign
Varshaphal	Tajika annual horoscope (Solar year return)
Nakshatra Deep Dive	Detailed Nakshatra analysis with deity, syllable, compatibility
Remedies	Gemstones, Mantras, Charity, Fasting based on chart afflictions

🌍 Western (Tropical)

Feature	Description
Natal Chart	Full tropical chart with Placidus / Koch / Equal houses
Aspects	11 aspect types with configurable orbs
Essential Dignities	Domicile, Exaltation, Detriment, Fall, Term, Face
Secondary Progressions	Day-for-a-year progressed chart
Solar Arc Directions	Arc-directed planetary positions
Solar Return	Annual return chart
Lunar Return	Monthly return chart
Synastry	Cross-chart aspects for relationship analysis
Composite Chart	Midpoint composite chart
Midpoint Analysis	Natal & synastry midpoint trees
Arabic Parts	Part of Fortune, Spirit, Love, and 8 more
Fixed Stars	31 major stars with conjunctions and parans
Asteroids	Chiron, Ceres, Pallas, Juno, Vesta

📅 Timing & Prediction

Feature	Description
Panchang	Tithi, Nakshatra, Yoga, Karana, Sunrise/Sunset
Muhurta	Quality assessment for any activity + auspicious time finder
Planetary Hours	Hora chart for any day
Eclipse Impacts	Detect eclipses hitting natal planets (conjunction/opposition)
Retrograde Calendar	Mercury through Saturn retrograde periods for any year
Transit Aspects	Real-time transit-to-natal aspects
Outer Planet Transits	Jupiter, Saturn, Rahu/Ketu over natal chart
Planetary Ingresses	Sign-change dates for all planets
AstroCartoGraphy	ACG lines for relocation astrology

---

🛠️ All 48 MCP Tools

Every tool is available to Claude Desktop (or any MCP client) via the AstroConsultant server.

<details> <summary><b>Click to expand full tool list</b></summary>

#	Tool Name	Category
1	get_natal_chart	Core
2	get_vedic_kundli	Vedic
3	get_varga_chart	Vedic
4	get_sade_sati	Vedic
5	get_bhava_chalit_chart	Vedic
6	get_upagrahas	Vedic
7	get_remedies	Vedic
8	get_gochar_report	Vedic
9	get_jaimini_karakas	Vedic
10	get_arudha_padas	Vedic
11	get_karakamsa	Vedic
12	get_yogas	Vedic
13	get_doshas	Vedic
14	get_gemstones	Vedic Remedies
15	get_mantras	Vedic Remedies
16	get_shadbala	Vedic
17	get_ashtakavarga	Vedic
18	get_lagna_lord_analysis	Vedic
19	get_transit_scoring	Vedic / Transits
20	get_current_dasha	Dasha
21	get_dasha_timeline	Dasha
22	get_dasha_interpretation	Dasha
23	get_yogini_dasha	Dasha
24	get_chara_dasha	Dasha
25	get_kalachakra_dasha	Dasha
26	get_varshaphal	Predictive
27	get_current_transits	Transits
28	get_eclipse_impacts	Transits
29	get_retrograde_calendar	Transits
30	get_now	Transits
31	get_panchang	Timing
32	get_muhurta	Timing
33	find_auspicious_time	Timing
34	get_planetary_hours	Timing
35	get_nakshatra_info	Timing
36	get_moon_phase	Timing
37	get_secondary_progressions	Western
38	get_solar_return	Western
39	get_lunar_return	Western
40	get_composite_chart	Western
41	get_synastry	Relationships
42	get_synastry_midpoints	Relationships
43	get_compatibility	Relationships
44	get_natal_midpoints	Analysis
45	get_arabic_parts	Analysis
46	get_astrocartography	Analysis
47	geocode_location	Utility
48	get_nakshatra_info	Utility
49	get_pro_analysis	PROFESSIONAL COMPLETE ANALYSIS

</details>

---

🚀 Quick Start

1. Install Dependencies

cd astrology-consultant
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. Download Ephemeris Files

python scripts/download_ephemeris.py

3. Start the API

uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

4. Verify

curl http://localhost:8000/utilities/health
# → {"status": "ok", "version": "1.0.0", ...}

---

🤖 Claude Desktop Integration

1. Start the FastAPI Server

source venv/bin/activate
uvicorn api.main:app --host 0.0.0.0 --port 8000

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "astro-consultant": {
      "command": "/FULL/PATH/TO/venv/bin/python",
      "args": ["/FULL/PATH/TO/astrology-consultant/mcp/server.py"],
      "env": {
        "MCP_FASTAPI_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

3. Restart Claude Desktop

Quit and reopen Claude Desktop. The 48 AstroConsultant tools will appear automatically.

---

📡 API Examples

Natal Chart

curl -X POST http://localhost:8000/natal/chart \
  -H "Content-Type: application/json" \
  -d '{
    "birth_data": {
      "name": "Test",
      "birth_year": 1990, "birth_month": 3, "birth_day": 15,
      "birth_hour": 14, "birth_minute": 30,
      "latitude": 28.6139, "longitude": 77.209,
      "timezone": "Asia/Kolkata"
    }
  }'

Vedic Kundli

curl -X POST http://localhost:8000/vedic/kundli \
  -H "Content-Type: application/json" \
  -d '{
    "birth_data": {
      "birth_year": 1990, "birth_month": 3, "birth_day": 15,
      "birth_hour": 14, "birth_minute": 30,
      "latitude": 28.6139, "longitude": 77.209,
      "timezone": "Asia/Kolkata"
    },
    "options": {"ayanamsa": "LAHIRI"}
  }'

Daily Panchang

curl -X POST http://localhost:8000/panchang/daily \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2026, "month": 3, "day": 6,
    "latitude": 28.6139, "longitude": 77.209,
    "timezone": "Asia/Kolkata"
  }'

Current Dasha

curl -X POST http://localhost:8000/vedic/dashas/current \
  -H "Content-Type: application/json" \
  -d '{
    "birth_data": {
      "birth_year": 1990, "birth_month": 3, "birth_day": 15,
      "birth_hour": 14, "birth_minute": 30,
      "latitude": 28.6139, "longitude": 77.209,
      "timezone": "Asia/Kolkata"
    }
  }'

Current Planetary Positions

curl http://localhost:8000/transits/now

---

📂 API Reference

Category	Endpoints	Description
/natal/*	10	Natal chart, planets, houses, aspects, dignities, midpoints, arabic parts
/vedic/*	20	Kundli, varga, dashas, yogas, shadbala, ashtakavarga, doshas, jaimini, lagna lord
/transits/*	10	Current transits, retrogrades, eclipses, ingresses, ashtakavarga scoring
/synastry/*	4	Cross-chart aspects, composite, Davison, compatibility
/panchang/*	5	Daily/monthly panchang, nakshatra, tithi, festivals
/muhurta/*	4	Quality assessment, auspicious time finder, hora
/western/*	5	Progressions, solar/lunar returns, composite chart
/timing/*	4	Solar/lunar returns, dasha interpretation, kalachakra
/fixed-stars/*	3	Star list, conjunctions, heliacal events
/utilities/*	9	Health, geocode, zodiac signs, nakshatras metadata

Total: 70+ endpoints · 48 MCP tools

---

🔧 Configuration

Supported Ayanamsas

LAHIRI · RAMAN · KRISHNAMURTI · FAGAN_BRADLEY · TRUE_CHITRAPAKSHA · YUKTESHWAR · JN_BHASIN · SASSANIAN

Supported House Systems

PLACIDUS · KOCH · WHOLE_SIGN · EQUAL · CAMPANUS · REGIOMONTANUS · PORPHYRY · ALCABITIUS · MORINUS · MERIDIAN · AZIMUTHAL · POLICH_PAGE

Zodiac Types

TROPICAL · SIDEREAL

---

🧪 Running Tests

source venv/bin/activate
python3 test_tools.py

Tests validate: Lagna Lord, Ashtakavarga Scoring, Dasha Interpretation, Kalachakra Dasha, Lunar Return, Eclipse Impacts, Retrogrades.

---

🐛 Troubleshooting

Issue	Solution
ModuleNotFoundError: swisseph	pip install pyswisseph
Inaccurate positions	Run python scripts/download_ephemeris.py
Port 8000 in use	Change API_PORT in .env
MCP not connecting	Ensure FastAPI server is running first
Timezone errors	Use IANA format: Asia/Kolkata, America/New_York
Chiron warnings	Non-critical — Chiron ephemeris data not available for all dates

---

📜 License

This project uses pyswisseph which is licensed under AGPL. Please review the Swiss Ephemeris license for commercial use requirements.

---

Created by Team Magicmond · Powered by Swiss Ephemeris