# socraticsurge/telugu-calendar-utilities [Health: Active]

**Category:** 🔮 Spirituality & Esoterica  
**Repository:** https://github.com/socraticsurge/telugu-calendar-utilities  
**GitHub Stars:** 1  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/socraticsurge-telugu-calendar-utilities

## Description
Telugu Panchangam (Hindu almanac): tithi, nakshatra, muhurta windows, 30+ festivals, tarabalam & chandrabalam good-day finder, gochara transits and a deterministic daily rasi phalalu — Swiss Ephemeris precision, every rule pinned against reference almanacs, by AstroChaganti. uvx mcp-server-panchangam.

## Tools
Capabilities this server exposes over MCP:

- **list_supported_cities** — Returns a JSON list of 22 pre-configured cities with name, latitude, longitude, timezone, and country. Call this first to discover valid city names.
- **get_panchangam** — Returns full Panchangam JSON for a date and city: Pancha Anga (Tithi, Nakshatra, Yoga, Karana), sky events (Sunrise, Sunset, Moonrise, Moonset), auspicious windows (Brahma Muhurta, Abhijit, Amrita Kalam), inauspicious windows (Rahu Kalam, Gulika, Yamagandam, Varjyam, Durmuhurtham), Choghadiya, special day flags, and field-group provenance states. New in 1.9.0: ghati_clock (sunrise-anchored ghati/vighati clock), nakshatra_pada (Moon's pada 1-4), vishaghati windows, bhadra_mukha/bhadra_puchha (Vishti split), sankramana_avoidance, in_panchaka_nakshatra, nakshatra_mukha (Adho/Urdhva/Tiryak), anandadi_yoga, is_khar_maasa/khar_maasa_name, is_pitru_paksha, simha_stha_guru/simha_stha_shukra (Drik only), guru_maudhya/shukra_maudhya (Drik only), disha_shoola_direction, panchaka_rahita. Args: date=YYYY-MM-DD, city=city name (or pass latitude+longitude for a custom location; timezone is derived if omitted), system=drik|surya_siddhanta|vakya (default: drik), ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha (default: lahiri; SS and Vakya accept the param for API symmetry but always use their own mean-motion model).
- **get_muhurta** — Returns auspicious and inauspicious time windows for a date and city as JSON. Lighter than get_panchangam — use for quick 'is this a good time?' queries. Includes field-group provenance and all 1.9.0 timing fields: vishaghati, bhadra_mukha/bhadra_puchha, sankramana_avoidance, ghati_clock, in_panchaka_nakshatra, nakshatra_mukha, anandadi_yoga, is_khar_maasa, is_pitru_paksha, simha_stha_guru/shukra, guru_maudhya/shukra_maudhya, disha_shoola_direction, panchaka_rahita. Args: date=YYYY-MM-DD, city=city name (or pass latitude+longitude; timezone is derived if omitted), system=drik|surya_siddhanta|vakya (default: drik).
- **get_special_days** — Returns a JSON list of special days in a given month: Ekadashi (fasting days), Amavasya (new moon), Pournami (full moon), Pradosham, Sankranti, and Eclipses. Args: year=e.g. 2026, month=1-12, city=city name (or pass latitude+longitude; timezone is derived if omitted), system=drik|surya_siddhanta|vakya (default: drik).
- **get_daily_horas** — Returns 24 planetary hours (horas) for a date and city as JSON. The 12 daytime horas start at sunrise and the 12 nighttime horas start at sunset. The first hora is ruled by the weekday lord. Args: date=YYYY-MM-DD, city=city name (or pass latitude+longitude; timezone is derived if omitted), system=drik|surya_siddhanta|vakya (default: drik).
- **get_lagna_transitions** — Returns Ascendant (Lagna) sign boundaries for a date and city as JSON, tracking the rising sign on the eastern horizon from sunrise to next sunrise. Args: date=YYYY-MM-DD, city=city name (or pass latitude+longitude; timezone is derived if omitted), system=drik|surya_siddhanta|vakya (default: drik).
- **get_panchangam_range** — Returns a compact Panchangam summary for each day in a date range (max 31 days). Each day includes: Tithi, Nakshatra, Yoga, Sunrise/Sunset, all auspicious and inauspicious windows, eclipse (if any), special yogas, and special day flags. New in 1.9.0: each day also carries all timing-computation fields — ghati_clock, nakshatra_pada, vishaghati, bhadra_mukha/bhadra_puchha, sankramana_avoidance, in_panchaka_nakshatra, nakshatra_mukha, anandadi_yoga, is_khar_maasa/khar_maasa_name, is_pitru_paksha, simha_stha_guru/shukra, guru_maudhya/shukra_maudhya, disha_shoola_direction, panchaka_rahita. Useful for planning muhurtas over a week or comparing multiple days. Args: start_date=YYYY-MM-DD, end_date=YYYY-MM-DD, city=city name, system=drik|surya_siddhanta|vakya (default: drik), ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha (default: lahiri).
- **get_combustion_calendar** — Returns Asta (heliacal setting / combustion entry) and Udaya (heliacal rising / re-emergence) periods for the five classical planets — Mercury, Venus, Mars, Jupiter, Saturn — over a date range for a given city. Asta marks when a planet becomes invisible due to proximity to the Sun; Udaya marks when it re-emerges. This matches the Drik Panchang Asta/Udaya calendar (sky-visibility criterion), not the fixed BPHS elongation Maudhya thresholds used in per-day combustion flags. Accuracy: within 1–2 days of Drik Panchang for most planets; Mars ±2 days. Max date range: 366 days. Args: start_date=YYYY-MM-DD, end_date=YYYY-MM-DD, city=city name (or pass latitude+longitude; timezone derived if omitted), planets=optional subset e.g. ['Saturn', 'Jupiter'] (default: all five).
- **get_graha_yuddha** — Returns Graha Yuddha (planetary war) periods in a date range. A planetary war occurs when two of the five tara grahas — Mercury, Venus, Mars, Jupiter, Saturn — come within 1° of each other in ecliptic longitude. The planet with the higher ecliptic latitude (more northerly) at the closest approach is the victor; the vanquished loses astrological strength for the duration. The Sun, Moon, Rahu, and Ketu are exempt by classical convention. Each war entry includes: the two planets, winner, loser, start/exact/end times in UTC, and minimum separation in arc-minutes. Max date range: 366 days. Args: start_date=YYYY-MM-DD, end_date=YYYY-MM-DD, planets=optional subset e.g. ['Venus', 'Jupiter'] (default: all five, yielding all 10 pair combinations).
- **get_rashi_ingresses** — Returns all rashi (sign) ingress events for the classical planets over a date range. A rashi ingress is when a planet crosses from one zodiac sign into the next — the foundational event for gochara (transit) period boundaries. Sidereal coordinates (ayanamsa-configurable). Includes retrograde ingresses (a planet re-entering a sign it recently left). Each entry has: planet, rashi entered, enters (UTC), exits (next ingress, UTC — may fall outside the range). Planets with no sign change in the range (e.g. Saturn in Meena all of 2026) do not appear. Supported planets: Sun, Mercury, Venus, Mars, Jupiter, Saturn, Rahu, Ketu. Moon is excluded (too frequent — a sign every ~2.25 days). Max range: 366 days. Args: start_date=YYYY-MM-DD, end_date=YYYY-MM-DD, planets=optional subset (default: all eight), ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha (default: lahiri).
- **get_eclipse_calendar** — Returns all solar and lunar eclipses in a date range with per-city visibility and Sutak timing. Each eclipse entry includes: kind (Solar/Lunar), subtype (Total/Annular/Partial/Penumbral), visible (whether it is observable from the given city), start/end times in local time, and sutak (ritual impurity window — 12 hours before Solar, 9 hours before Lunar) for visible eclipses only. Max range: 730 days (two years). Args: start_date=YYYY-MM-DD, end_date=YYYY-MM-DD, city=city name (or pass latitude+longitude; timezone derived if omitted).
- **get_panchanga_shuddhi** — Panchanga Shuddhi — five-limb purity assessment for any date. Returns a verdict (Sarva Shuddha / Chatushka Shuddha / Tri Shuddha / Dvi Shuddha / Eka Shuddha / Sarva Ashuddha) and a per-limb breakdown (Tithi, Vaara, Nakshatra, Yoga, Karana) with quality ('shuddha' | 'ashuddha' | 'mixed') and a one-line reason for each. Rules: Tithi — Rikta (4th/9th/14th) are ashuddha; Vaara — Mon/Wed/Thu/Fri are shuddha, Sun/Tue/Sat are ashuddha; Nakshatra — Laghu/Mridu/Dhruva/Chara are shuddha, Tikshna/Ugra are ashuddha, Krittika/Vishakha are mixed; Yoga — the 17 Nitya auspicious yogas are shuddha, Vyatipata/Vaidhriti are ashuddha, partial-dosha yogas (Vishkambha/Atiganda/Shoola/Ganda/Vyaghata/Parigha) are mixed; Karana — Vishti (Bhadra) and the four fixed karanas are ashuddha, all movable karanas are shuddha. Values are taken at sunrise. Args: date=YYYY-MM-DD, city=city name (or latitude+longitude), system=drik|surya_siddhanta|vakya (default: drik).
- **find_tarabalam_days** — Find which upcoming days are auspicious for one or more people based on their janma (birth) nakshatras — Tarabalam, optionally combined with Chandrabalam. Returns per-day taras (Janma/Sampat/Vipat/Kshema/Pratyak/Sadhana/Naidhana/Mitra/Parama Mitra) for each person plus good_for_all_dates listing days auspicious for everyone. Pass janma_rasis (aligned with janma_nakshatras, null entries allowed) to also check Chandrabalam — each person then gets a chandra position/verdict (good | puja | bad) and good_for_all requires both checks to pass. Args: janma_nakshatras=1-4 birth stars (canonical spellings, e.g. 'Ashvini', 'Uttara Bhadrapada'), start_date=YYYY-MM-DD, days=1-60 (default 14), city=city name (or latitude+longitude), system=drik|surya_siddhanta|vakya, janma_rasis=optional birth rashis (e.g. 'Meena'), chandra_mode=how the Moon affects good_for_all: 'stars' (annotate only, matches classic tarabalam tables — default), 'puja_ok' (drop Moon-avoid days), 'strict' (Moon must be good).
- **get_graha_positions** — Sidereal positions of all nine grahas — Surya, Chandra, Kuja, Budha, Guru, Shukra, Shani, Rahu, Ketu — at sunrise of the given date: longitude, rasi, nakshatra, pada, retrograde flag, and when each graha enters its next rasi (rasi_until + next_rasi; transit/gochara groundwork). Args: date=YYYY-MM-DD, city=city name (or latitude+longitude; timezone derived if omitted), ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha (default: lahiri).
- **get_gochara** — Gochara (transit) verdicts for a janma rasi (natal Moon sign): each of the nine grahas with its house position counted from the janma rasi and a verdict (favourable | blocked by vedha | adverse). Brihat Samhita 104.4 supports the seven classical grahas' favourable houses; Phaladeepika 26.3-8 supports the Vedha pairs and exemptions. Phaladeepika 26.2 supports the configured Rahu/Ketu houses 3, 6, 10 and 11 by treating both nodes like Surya; node Vedha remains unverified. Phaladeepika 26.1 and 26.22-23 support the Moon reference and underlying named-Shani house effects, not the conventional names, phase labels or advice. Positions are at sunrise. Args: date=YYYY-MM-DD, janma_rasi=e.g. 'Mesha' (canonical rashi spellings), city=city name (or latitude+longitude), ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha (default: lahiri).
- **get_rasi_phalalu** — Daily Rasi Phalalu — a deterministic daily reading for a janma rasi, rendered entirely from computed facts: the Moon's chandrabalam house sets the day quality, each graha's gochara verdict (with vedha) becomes one traceable sentence, Sade Sati/Ashtama Shani are stated when running, and passing janma_nakshatra adds the day's tarabalam line. Not fiction: every line maps to a calculation. Args: date=YYYY-MM-DD, janma_rasi=e.g. 'Mesha', janma_nakshatra=optional birth star for the tara line, city=city name (or latitude+longitude), ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha (default: lahiri).
- **find_muhurta** — Find ranked auspicious time slots over the coming days. Slots are good choghadiya blocks (Amrit/Shubh/Labh/Char) with every inauspicious window subtracted (Rahu Kalam, Gulika, Yamagandam, Varjyam, Durmuhurtham), scored with Abhijit Muhurta / Amrita Kalam overlap and special-yoga bonuses. Activity-specific source profiles add their own hard and manual gates; ceremony is narrowly Shantika/Paushtika, and beginning is narrowly Dharma-kriya commencement. New in 1.9.0: Bhadra Mukha is a hard-avoid cut; Simha-Stha Guru/Shukra, Guru/Shukra Maudhya (combustion), Khar-Maasa, Adhika Maasa, and Pitru Paksha are all skipped for samskara activities; Panchaka Rahita (Mrityu/Agni/Raja/Chora/Roga) is checked at both day-level (sunrise lagna) and slot-level; optional travel_direction activates Disha Shoola filtering. The legacy activity name litigation resolves to the verified court filing profile and has no separate Bhadra Puchha bonus. Pass janma_nakshatras (1-4 birth stars) to keep only days whose tarabalam favours everyone. Optionally pass janma_rasis (aligned with janma_nakshatras, null entries allowed) to add Chandrabalam scoring, and janma_lagnas for strict Lagna Shuddhi. include_night=True adds night slots with night-specific scoring. Args: start_date=YYYY-MM-DD, days=1-14, activity=one of the published activity keys, city=city name (or latitude+longitude), system=drik|surya_siddhanta|vakya, chandra_mode=stars|puja_ok|strict, ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha, travel_direction=optional N/S/E/W/NE/NW/SE/SW, include_night=false|true.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "telugu-calendar-utilities": {
    "command": "uvx",
    "args": ["mcp-server-panchangam"]
  }
}
```

## Documentation & README

# Telugu Panchangam Calendar Feeds

Subscribable Telugu Panchangam feeds for 22 cities — delivered as `.ics` files you can add to Google Calendar, Apple Calendar, or Outlook.

Every day appears as an all-day event (no calendar blocking) with full Panchangam details in the description. Festival days — Ugadi, Vinayaka Chavithi, Deepavali, Maha Shivaratri, the Sankranti cluster, and 30+ more — are marked with 🪔 in the title; other special days (Ekadashi, Amavasya, Pournami, Pradosham, Sankranti, Eclipses) with ⚡.

![Today's Panchangam at panchangam.astrochaganti.com](https://raw.githubusercontent.com/socraticsurge/telugu-calendar-utilities/HEAD/docs/screenshots/01-panchangam.png)

## Subscribe

Visit the landing page to pick your city and calculation system and copy your `webcal://` URL:

**[panchangam.astrochaganti.com](https://panchangam.astrochaganti.com)**

The site is also a daily toolkit: **Today's Panchangam** (any date, any city), **Tarabalam · Muhurtam**
(good days and ranked time slots for up to four people by birth star, with Chandrabalam), and the
**Gochara chart with Rasi Phalalu** (South Indian chart, transit verdicts and a computed daily reading).
Guests can also create browser-local profiles from known astrology details. Local development and an
explicitly activated public build can calculate Nakshatra, Padam, Janma Rashi, Lagna, and a reviewable
D1 chart from date, exact time, and birthplace. Public builds fail closed until the licensed calculation
service and place provider are approved; saved calculated profiles remain viewable. The name never leaves
the browser. See the [calculation and privacy contract](https://github.com/socraticsurge/telugu-calendar-utilities/blob/HEAD/docs/reference/53-birth-profile-calculation.md).
Drik Muhurtam searches also contain a source-backed candidate-time chart
post-screen, guarded by an independent fail-closed flag. Public builds make no
chart request unless `VITE_ELECTION_CHART_API_ENABLED` is exactly `true`; see
the [screening method and release boundary](https://github.com/socraticsurge/telugu-calendar-utilities/blob/HEAD/docs/reference/54-muhurtam-election-chart-screening.md).
Everything is shareable to WhatsApp.

<details>
<summary>What subscribing looks like</summary>

![Subscribe flow — pick a feed, copy the webcal URL, add to your calendar](https://raw.githubusercontent.com/socraticsurge/telugu-calendar-utilities/HEAD/docs/screenshots/02-subscribe.png)

</details>

## What's in each day's event

- **Metadata** — Samvatsara, Maasam, Paksham, Vaaram, solar and lunar signs
- **Pancha Anga** — Tithi, Nakshatra, Yoga, Karana with start/end times
- **Sky markers** — Sunrise, Sunset, Moonrise, Moonset
- **Auspicious windows** — Brahma Muhurta, Abhijit Muhurta, Amrita Kalam
- **Inauspicious windows** — Rahu Kalam, Gulika Kalam, Yamagandam, Varjyam, Durmuhurtham
- **Choghadiya** — 8 day blocks with names
- **Eclipses** — Solar and lunar eclipses with type (Total/Partial/Annular/Penumbral), visibility from your city, eclipse window, and Sutak period
- **Special Yogas** — Sarvartha Siddhi, Amrita Siddhi, Visha, and Dagdha yogas based on weekday/tithi/nakshatra combination

## Cities

**Telugu Heartland** — Hyderabad, Vijayawada, Visakhapatnam, Tirupati, Warangal, Guntur, Nizamabad, Rajahmundry, Kurnool, Nellore

**Major Indian Metros** — Bengaluru, Chennai, Mumbai, Delhi

**International Diaspora** — Dallas, San Jose, San Francisco, Edison (NJ), New York, London, Sydney, Dubai

## Calculation Systems

| System | Basis | Best for |
|--------|-------|----------|
| **Drik Ganita** | Swiss Ephemeris (pyswisseph) — supports Lahiri, Raman, Krishnamurti, True Chitrapaksha ayanamsas | Modern apps, accurate sky events |
| **Surya Siddhanta** | Mean-motion algorithms from classical SS text | Traditions rooted in classical siddhantic calculation |
| **Vakya** | Surya Siddhanta + published correction tables | Traditional Telugu/Tamil printed Panchangams |

## MCP Server

`mcp-server-panchangam` is available on PyPI. It's a standard MCP stdio server (`uvx mcp-server-panchangam`), so it works with any MCP-compatible client or agent — Claude Desktop, Claude Code, Cursor, Windsurf, and custom agents built on the MCP SDK. Below are examples for a couple of common clients; for others, point your client's MCP config at the same `uvx mcp-server-panchangam` command.

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "panchangam": {
      "command": "uvx",
      "args": ["mcp-server-panchangam"]
    }
  }
}
```

**Claude Code** — run once:

```bash
claude mcp add panchangam -- uvx mcp-server-panchangam
```

### Available tools

**Daily Panchangam**

| Tool | Description |
|------|-------------|
| `get_panchangam` | Full Panchangam for any date and city |
| `get_muhurta` | One day's auspicious/inauspicious windows (lighter call; use `find_muhurta` to search across days) |
| `get_panchanga_shuddhi` | Five-limb purity verdict (Sarva Shuddha → Sarva Ashuddha) with per-limb quality and reason |

**Planning across days**

| Tool | Description |
|------|-------------|
| `get_panchangam_range` | Compact Panchangam summary for each day in a range (max 31 days) |
| `get_special_days` | Named festivals, Ekadashi, Amavasya, Pournami, Pradosham, Sankranti, and Eclipses for a month |
| `find_muhurta` | Ranked auspicious time slots — activity-aware, every slot with its reasons |
| `find_tarabalam_days` | Tarabalam & Chandrabalam — days favourable for 1–4 people by birth star (and rashi) |

**Sky events**

| Tool | Description |
|------|-------------|
| `get_combustion_calendar` | Asta/Udaya (combustion entry/exit) periods for Mercury, Venus, Mars, Jupiter, Saturn |
| `get_graha_yuddha` | Graha Yuddha (planetary war) periods — winner, loser, timing in UTC |
| `get_rashi_ingresses` | All rashi sign-change events for the classical planets over a date range |
| `get_eclipse_calendar` | Solar and lunar eclipses with per-city visibility and Sutak timing |

**Gochara and personal transits**

| Tool | Description |
|------|-------------|
| `get_graha_positions` | All nine grahas at sunrise — rasi, nakshatra, retrograde, next-rasi dates |
| `get_gochara` | Gochara verdicts from a janma rashi — houses, vedha, Sade Sati / Ashtama Shani |
| `get_rasi_phalalu` | Deterministic daily reading rendered from computed facts |

**Intraday timing**

| Tool | Description |
|------|-------------|
| `get_daily_horas` | 24 planetary hours (horas) for the day, starting at sunrise with the weekday lord |
| `get_lagna_transitions` | Ascendant (Lagna) sign boundaries tracking the eastern horizon across the day |

**Utility**

| Tool | Description |
|------|-------------|
| `list_supported_cities` | 22 pre-configured cities with lat/lon/timezone |

All tools accept any free-text city name. Pre-configured cities resolve instantly; any other city is geocoded via OpenStreetMap. You can also pass `latitude`, `longitude`, and `timezone` directly.

Drik-system tools that accept a `city` or date also accept `ayanamsa=lahiri|raman|krishnamurti|true_chitrapaksha` (default: `lahiri`). Full API documentation and parameter details: [mcp-server-panchangam on PyPI](https://pypi.org/project/mcp-server-panchangam/).

## How it works

Feeds are generated on the 1st of every month via GitHub Actions, covering 18 months ahead. They are served as static `.ics` files from GitHub Pages — zero hosting cost.

```
GitHub Actions (monthly cron)
  → python -m telugu_panchangam.generate   (22 cities × 3 systems = 66 feeds)
  → feeds/*.ics
  → GitHub Pages (webcal:// subscriptions)
```

## Maintenance and roadmap

The active maintenance queue is the
**[Telugu Calendar Utilities GitHub Project](https://github.com/users/socraticsurge/projects/2)**.
Use the linked status and priority fields to see what is planned, in progress,
or ready for review. File defects and feature proposals in
**[repository Issues](https://github.com/socraticsurge/telugu-calendar-utilities/issues)**.

The CSV files and phase plans under `docs/tracking/` are preserved historical
records; they are not a second backlog.

## Documentation

The repository is the canonical documentation source. Start with the
**[documentation standard](https://github.com/socraticsurge/telugu-calendar-utilities/blob/HEAD/docs/README.md)** for where current reference,
operations, decisions, and historical material belong, then use the
**[computation reference index](https://github.com/socraticsurge/telugu-calendar-utilities/blob/HEAD/docs/reference/README.md)** for the detailed
system map. A searchable VitePress projection is built from these files at
`/docs/`; it is disposable presentation output and does not replace the
repository as the source of truth.

## License and corresponding source

Copyright (C) 2026 Vinay Chaganti.

This project is free software under the
[GNU Affero General Public License v3.0 or later](https://github.com/socraticsurge/telugu-calendar-utilities/blob/HEAD/LICENSE). Users of the
website and MCP package can obtain the complete corresponding source,
including build instructions and tests, from this repository. Direct
dependency notices for PySwissEph and Swiss Ephemeris are preserved in
[THIRD_PARTY_NOTICES.md](https://github.com/socraticsurge/telugu-calendar-utilities/blob/HEAD/THIRD_PARTY_NOTICES.md).

This project selects the AGPL path in Swiss Ephemeris's dual-license model.
Earlier copies remain available under the licence terms conveyed with those
copies; this release does not withdraw an earlier grant.

## Development

Requires Python 3.10+, [uv](https://docs.astral.sh/uv/), and Node.js 24.

```bash
uv sync --locked --extra test --extra browser-test
uv run playwright install chromium
npm ci --ignore-scripts
uv run python tools/verify_project.py
uv run python -m telugu_panchangam.generate   # writes to feeds/
```