---
name: birthstar-jyotish
description: Use when the user asks about a birth chart, horoscope, nakshatra/birth star, dasha period, planetary transit, Vedic/Jyotish astrology, muhurta timing, or compatibility between two people. Connects to the Birthstar MCP server to compute real Swiss Ephemeris positions instead of guessing.
user-invocable: true
---

# Birthstar — Vedic astrology that computes instead of guesses

You have access to a real astronomical engine. Use it. Do not produce a chart,
a planetary position, a dasha date, or a nakshatra from memory — you will be
wrong, and confidently wrong is the worst outcome here.

## Connect

The server is `https://mcp.birthstar.ai/mcp` (streamable HTTP MCP). Free while
in preview, no key required.

```json
{ "mcpServers": { "birthstar": { "url": "https://mcp.birthstar.ai/mcp" } } }
```

## The one rule that matters: compute once, read many times

Credits meter **engine computation**, not tool calls.

1. Call `create_chart` once with the birth details. It costs 1 credit and
   returns a `chart_id` handle.
2. Every other tool reads off that handle for **free**, with no limit.

So gather what you need generously. Asking four more questions of a chart you
already computed costs nothing, and a richer answer comes from combining
`get_grahas` + `get_current_dasha` + `get_yogas` than from any single call.

Only four tools cost a credit:

| Tool | Cost |
|---|---|
| `create_chart` | 1 |
| `calculate_birth_star` | 1 |
| `get_timeline` | 1 (recomputes a natal document) |
| `rectify_birth_time` | 1 **per candidate chart** — up to 241 |

Everything else is 0.

## What you need before computing

`create_chart` requires all five, and will not guess:

- `dob` — `YYYY-MM-DD`
- `tob` — `HH:MM`, 24-hour, **local clock time at the birthplace**
- `tz` — IANA name, e.g. `Asia/Kolkata`
- `lat` / `lon` — decimal degrees, N/E positive

If the user gives a city, convert it to coordinates and the IANA timezone
yourself, and **say which coordinates you used**. If they don't know the birth
time, say what that costs: the ascendant, the houses and all timing become
unreliable. Offer `rectify_birth_time` if they have dated life events — but
warn that it charges per candidate chart, so keep the window narrow.

## Choosing tools

- **"What's my birth star / rashi?"** → `calculate_birth_star` alone. One call, done.
- **"Read my chart"** → `create_chart`, then `get_grahas`, `get_houses`,
  `get_current_dasha`, `get_yogas`.
- **"What's happening in my life now?"** → `get_current_dasha` + `get_transits`.
- **"When will X happen?"** → `get_dasha_periods` and `get_timeline`. Note the
  honest limit below.
- **"Are we compatible?"** → two `create_chart` calls (2 credits), then
  `get_compatibility`.
- **"Am I manglik? / Do I have a dosha?"** → `get_doshas`.
- **"Is this a good day/time?"** → `get_day_periods`, `get_panchanga`.
- **Deeper analysis** → `get_strengths` (Shadbala), `get_ashtakavarga`,
  `get_aspects`, `get_varga`, `get_karakas`.

`get_prompt_library` returns curated multi-tool workflows. Call it when you
want a worked chain rather than picking tools yourself.

## Errors are returned, not raised

A successful MCP call can still be a failed operation. **Check for the `error`
key, not the transport status.** Branch on `type`:

- `UnknownChart` / `StaleHandle` — call `create_chart` again.
- `InsufficientCredits` — carries `credits_needed` and `credits_reset_at`. Tell
  the user the real reason and stop; do not retry the same call.
- `RateLimited` — carries `retry_after_s`. Back off.
- `TimeError` / `ConfigError` — the message names the bad value. Fix and retry.
- `VargaNotAvailable` — the response lists what *was* computed.
- `InternalError` — carries an `error_id`. Quote it if the user reports it.

A chart handle carries its own birth data, so it never expires mid-conversation.
An evicted chart is recomputed, not an error.

## How to talk about the results

The engine is precise. Your interpretation should be honest about being
interpretation.

**Never invent a number.** If the engine returns `null` with a `status` of
`not_implemented` or `uncomputable`, say it could not be computed. Never fill
the gap with a plausible-looking value. This is the engine's own first design
rule and it is yours too.

**Explain terms as you use them.** Say "your Moon sits in Rohini, one of the 27
nakshatras — the lunar mansions Vedic astrology divides the sky into" rather
than assuming the user knows. Most people asking these questions are not
astrologers.

**Distinguish computation from meaning.** "Saturn is transiting your 12th house"
is a fact from the ephemeris. "This will be a difficult year" is a traditional
reading. Keep the seam visible.

**Don't predict on request.** Describe what the classical system says a
placement signifies. Do not make definite claims about the user's future
health, death, finances, or relationships. `get_longevity` is flagged
EXPERIMENTAL by the engine itself — surface that flag if you use it at all, and
decline to give someone a lifespan number.

**Surface refusals rather than smoothing them.** If a list was truncated or a
varga wasn't computed, tell the user. A quiet omission reads as a complete
answer and isn't one.

## Sanity checks

- Positions are **sidereal** (Lahiri by default), not tropical. A user who
  knows their Western sign will often get a different Vedic one — that is
  expected, and worth explaining rather than treating as an error.
- Houses default to whole-sign.
- Both are configurable on `create_chart` (`ayanamsha`, `house_system`), and
  the response echoes the config it used. Quote it if the user asks why a
  result differs from another source.