Metadata-Version: 2.4
Name: mcp-server-panchangam
Version: 1.3.0
Summary: MCP server for Panchangam calculations — Tithi, Nakshatra, Yoga, Muhurtas for any city
License: MIT
Keywords: panchangam,vedic,astrology,mcp,calendar
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: pyswisseph>=2.10.3
Requires-Dist: pytz>=2024.1
Requires-Dist: geopy
Requires-Dist: timezonefinder
Requires-Dist: icalendar>=5.0.0
Dynamic: license-file

# mcp-server-panchangam

An MCP (Model Context Protocol) server that gives AI assistants accurate Telugu/Vedic Panchangam data — Tithi, Nakshatra, Yoga, Karana, sky events, and auspicious/inauspicious time windows — for any city and date.

## Installation

This is 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
```

## Tools

### `list_supported_cities`

Returns 22 pre-configured cities with name, latitude, longitude, timezone, and country. Call this first to discover valid city names.

### `get_panchangam(date, city, system="drik", latitude=None, longitude=None, timezone=None)`

Full Panchangam for a date and city:

- **Metadata** — Samvatsara, Ayanam, Rituvu, Maasam, Paksham, Vaaram, solar and lunar signs
- **Pancha Anga** — Tithi, Nakshatra, Yoga, Karana with start/end times
- **Sky events** — 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
- **Festivals** — 30+ named Telugu festivals (Ugadi, Vinayaka Chavithi, Deepavali, Maha Shivaratri, Makara Sankranti cluster, Navaratri days, Varalakshmi Vratam, …) plus monthly Sankashti Chaturthi and Masa Shivaratri, with traditional deciding moments (madhyahna/aparahna/pradosha/nishita)
- **Special day flags** — Ekadashi, Amavasya, Pournami, Pradosham, Sankranti, Ganda Moola
- **Eclipse** — Solar/lunar eclipse with type (Total/Partial/Annular/Penumbral), visibility from your location, eclipse window, and Sutak period (or `null` if not visible)
- **Special Yogas** — Sarvartha Siddhi, Amrita Siddhi, Visha, and Dagdha yogas

### `get_muhurta(date, city, system="drik", latitude=None, longitude=None, timezone=None)`

Auspicious and inauspicious time windows only — a lighter call for quick "is this a good time?" queries.

### `find_tarabalam_days(janma_nakshatras, start_date, days=14, city="Hyderabad", system="drik", ...)`

Tarabalam & Chandrabalam: pass 1-4 birth stars (e.g. `["Uttara Bhadrapada", "Purva Ashadha"]`) and get each day's tara per person (Janma/Sampat/Vipat/Kshema/Pratyak/Sadhana/Naidhana/Mitra/Parama Mitra) plus `good_for_all_dates` — days auspicious for everyone at once. Optionally pass `janma_rasis` (aligned, null entries allowed) to also check Chandrabalam — each person then gets the Moon's position from their rashi with a verdict (good / needs remedial puja / avoid), and `chandra_mode` selects how it affects `good_for_all`: `stars` (annotate only — default, matches classic tarabalam tables), `puja_ok`, or `strict`. Up to 60 days per call.

### `get_special_days(year, month, city, system="drik", latitude=None, longitude=None, timezone=None)`

Lists special days in a given month: named festivals, Ekadashi (fasting), Amavasya (new moon), Pournami (full moon), Pradosham, Sankranti, Ganda Moola, and Solar/Lunar Eclipses. Each entry includes a `special_yogas` list for that day.

## Cities and locations

`city` accepts any of the 22 pre-configured cities (instant, no network) or any free-text city name (geocoded via OpenStreetMap). You can also bypass city lookup entirely by passing `latitude`, `longitude`, and `timezone` directly.

**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` | Swiss Ephemeris (pyswisseph) + Lahiri ayanamsa | 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 |

## Source

Source code, tests, and the related Panchangam calendar feed project: https://github.com/socraticsurge/telugu-calendar-utilities
