Wire in five minutes.
Tools live from the server.
The tool catalog below is rendered live from mcp.kundalimcp.com/mcp via ISR — it cannot drift from reality.
tools/list, so it cannot drift.Direct API — from zero to a real chart in three steps.
Every authenticated request is JSON-RPC 2.0 over HTTPS to https://mcp.kundalimcp.com/mcp.
Get an API key
Sign up at kundalimcp.com/pricing, create a key from your dashboard, and pass it as a Bearer token. Keys are prefixed sutra_ followed by 32 hex characters.
Authorization: Bearer sutra_<32 hex chars>Cast your first chart
Five required fields: birth_datetime (local clock time at the birth place, ISO 8601 naive — no Z, no offset; the server resolves the historical timezone from the coordinates), latitude, longitude, school, locale. Everything else defaults — see Tools below for the full input schema.
curl -X POST https://mcp.kundalimcp.com/mcp \
-H "Authorization: Bearer sutra_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "kundali",
"arguments": {
"birth_datetime": "1990-01-15T05:00:00",
"latitude": 28.6139,
"longitude": 77.2090,
"school": "parashari",
"locale": "en"
}
}
}'Read the response
You get a content-addressed ChartArtifact — planet positions, divisional charts, qualified yogas, dasha timeline, panchanga, and classical citations — all in the requested locale. The chart_hash identifies it for idempotency / dedupe; it is not a shortcut for follow-up calls — every chart-anchored tool re-supplies the underlying birth data (either as flat birth_datetime/latitude/longitude fields directly, or wrapped in a chart_ref object). The resulting artifact is auto-cached in encrypted form keyed off your API key (operator-blind), TTL up to 30 days. Pass cache: “skip” per-call to disable.
The exact field set evolves with the API version surfaced in every _meta.api_version. Read one response to learn the shape; introspect tools/list to wire types in code.
Two steps to your first Jyotish answer.
KundaliMCP is a native MCP server — Claude, ChatGPT, and any other MCP host connect directly. No SDK, no adapter. Add the server, paste the system prompt, ask about your chart.
Add the MCP server
In your AI client, add a new MCP server and paste the endpoint URL. Authorize with OAuth (one click) or use a sutra_ API key as the bearer token.
https://mcp.kundalimcp.com/mcpAdd the system prompt
Paste this into your AI's custom instructions or system prompt. It encodes seven rules the server expects the agent to follow — chart-first discipline, boundary sensitivity, classical citation, locale fidelity, privacy scope — so you don't have to re-teach them every session.
You are using KundaliMCP, a Vedic Jyotish computation server. The server is the source of truth — never paraphrase astrology from memory; always read it from a tool response.
1. CHART FIRST. When the user supplies birth data (datetime + latitude + longitude), call kundali before answering any chart-related question. Every chart-anchored tool accepts the flat fields (birth_datetime + latitude + longitude) directly; a chart_ref object wrapping the same three fields also works. chart_hash is for bookkeeping (idempotency, dedupe), not for skipping re-supply.
2. ONE CALL, MANY SECTIONS. kundali returns the chart AND its sections from a single computation. Yogas, the Vimshottari timeline, the forward dasha reading, current transits, remedies, graha positions and the birth panchanga all ship by DEFAULT — do not make a second call for them. Add more with include, a comma-separated list: vargas (divisional charts; pass vargas: ["D9","D10"]), classical_rules (the cited rules that fired, LARGE — bound it with classical_rules_limit: N per bhava, or classical_rules_bhavas: [7,2] to keep only the houses you asked about), narrative (a plain-language reading for one domain), transit_events (ingresses/stations/returns across a window; pass transit_start and transit_end), reasoning and idl. A section parameter sent WITHOUT its include token is an error, not a no-op.
3. RESPECT BOUNDARY SENSITIVITY. kundali returns an idl.boundary_margins block flagging placements near nakshatra / pada / sign cusps. If anything has boundary_sensitive: true, ask the user to confirm exact birth time before quoting any nakshatra-, pada-, or D9-based prediction.
4. PICK THE RIGHT TOOL FOR TIME.
- Active dasha, forward reading, and the sky right now: already in the kundali response (dashas, dasha_forecast, transits).
- Deeper Vimshottari levels: kundali with dasha_depth (1=MD, 2=MD+AD default, 3=+pratyantar).
- Significant transits across a range: kundali with include=transit_events plus transit_start and transit_end.
- Triggered life events: kundali with include=events. eval_date alone gives a snapshot at that date; add events_until for a horizon scan, which is what "when will I…" actually needs.
- Lifetime view (dasha tree, life-area trajectories, life events, sade sati, returns): lifemap.
- A day's panchanga at a place: panchang. An auspicious moment for an activity: shubh_muhurat.
- Why one specific claim is true, back to the ephemeris: pramaan, addressed by the concept URI the response already gave you (e.g. concept:yoga/gajakesari).
5. PRESERVE LOCALIZATION. Response strings are returned in the requested locale (en, hi, sa, ta, te, kn, bn). Quote them verbatim — never re-translate. If a response signals a locale fallback (English shown because that locale is not yet authored), surface the English and note the locale is pending.
6. CITE THE SOURCE. Every rule-based interpretation (yoga, gochara, dasha effect, life-event verdict) carries a classical citation in its response object. Quote the citation when stating a verdict.
7. PRIVACY. Birth data is processed in-process and may be cached in encrypted form, with cache lifetime up to 30 days. Cached entries are encrypted with material derived from your API key, which KundaliMCP cannot decrypt without your live key. Pass cache: "skip" per-call to disable.
8. SCOPE. KundaliMCP is Vedic / Indian-tradition only. Synastry, composite charts, Western aspects, Babylonian ayanamshas, Regiomontanus / Porphyry / Morinus / Alcabitius houses, and Western dignity are out of scope. If the user asks, redirect to the Vedic equivalent (e.g. kundali_milan for Kundali Milan) or decline.Ask your first question
Once connected, the agent calls kundali automatically when you give it birth data. Try:
I was born on January 15, 1990 at 5:00 AM in New Delhi.
Cast my Parashari chart in English.The agent will call kundali — one call returning graha positions, active yogas, the Vimshottari timeline, current transits, remedies, the birth panchanga and classical citations. All from the server, nothing from memory.
Two paths. One bearer header.
Two methods — both via Authorization: Bearer
- OAuth 2.1 — for interactive AI clients (Claude, ChatGPT). One-click connect; no secret to manage. Setup guides →
- API key — long-lived
sutra_…bearer for CI and server-to-server callers. Generate from dashboard →
Discovery methods (initialize, tools/list, ping, get_version) are unauthenticated — agents can introspect before paying.
API key format
Authorization: Bearer sutra_<32 hex chars>Storage
Keys are stored as SHA-256 hashes; plaintext is never persisted. Copy your key immediately on creation — it cannot be recovered.
Rotation
Create and revoke keys from your dashboard at any time. Revoked keys return 401 immediately.
Transport
TLS 1.3 required on all endpoints. HMAC signing available for webhook callbacks.
Best practice
Never embed keys in client-side code. Use environment variables or a backend proxy.
Every tool. Live schema.
Rendered directly from https://mcp.kundalimcp.com/mcp. If a field appears here, the server accepts it; if it doesn't, we don't document it because we can't guarantee it.
Discover from your agent in two unauthenticated calls
# What can this server do?
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
# What's the API version + protocol?
{"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"get_version","arguments":{}}}Both bypass auth; tools/call for any other tool requires a sutra_ key.
Datetime contract (applies to every tool)
All datetime inputs are local clock time at the relevant location — no Z, no ±HH:MM. The server resolves the historical UTC offset from latitude + longitude via IANA tzdata (chrono-tz historical record covers India 1955, US 1966, Russia 2011, and all DST regimes).
Every emitted datetime field carries both a <field>_utc value (RFC 3339 with Z) and a <field>_local value (naive local clock face at the natal IANA zone, DST-aware at that moment). Each chart-anchored response also carries a top-level birth_context block with tz_iana, tz_offset_minutes_at_birth, birth_datetime_local, birth_datetime_utc, and dst_note (set only on DST fall-back ambiguity). Clients do not need a timezone library.
kundali
Compute a Vedic (Jyotish) birth chart.
Tier: All · Typical default response: ~6 KB.
Response shape
Returns: · headline: one-sentence summary the user can quote · facts.lagna / facts.chandra / facts.surya — top-asked facts inline · facts.planets — dict keyed by graha name (sun, moon, mars, ...) · facts.bhavas — dict keyed by 1-12 · facts.active_dasha — current Vimshottari period across 5 levels · facts.sade_sati — phase + prev/next windows · facts.active_yogas — the yogas present, ranked by significance (up to 10), each with strength, `description` (localised) and `classical_locus` · facts.chart_ref — thread to subsequent tools to skip re-supplying birth data Everything above comes from ONE computation. Add sections with `include` — `vargas` (divisional charts, with a `vargas` array), `classical_rules` (the cited classical rules that fired, LARGE), `narrative` (a plain-language reading for one `domain`), `reasoning` and `idl`. Sections not named there already ship.
Sections · one call, not several
Ships by default — do not ask for these:
active_yogasdashasdasha_forecasttransitsremediesplanetspanchangaOpt-in — add with include (comma-separated):
classical_ruleslargeclassical_rules_limitclassical_rules_bhavasCited classical rules that fired on this chart, each with its source locus, at `facts.kundali_insights`. LARGE — ~61 KB; pass `classical_rules_limit: N` to keep only the N highest-confidence rules PER BHAVA (per-bhava totals are preserved in the section marker so "N of M shown" stays renderable).
eventseval_dateevents_untilLifetime forecast events with likelihood band, confidence, why-clauses and per-factor breakdown, evaluated at `eval_date` (default: now). Two modes: `eval_date` alone gives a point-in-time SNAPSHOT of what is firing then; adding `events_until` (YYYY-MM-DD) runs a weekly SCAN across the window, keeping each event's strongest firing. A snapshot cannot answer "when will this happen", and there is no default horizon. Zero-confidence entries are withheld and counted in `suppressed_zero_confidence`.
transit_eventstransit_starttransit_endSign-ingresses, retrograde stations and returns across a date range. Needs `transit_start` and `transit_end`. Scans the window, so unlike other sections it costs compute.
vargasvargasDivisional charts. Defaults to D9 when the section is named without the parameter.
narrativedomainPlain-language reading for one life domain.
reasoninglargePer-claim why-clauses and audit trails. LARGE — 93.7% of the `events` section's bytes.
idllargeThe raw deterministic artifact, pre-shaping. LARGE, and a different register.
A section parameter sent without its include token is an error, not a no-op.
Input
skipmale · femaleen · hi · sa · ta · te · kn · bnparashari · jaimini · kplifemap
Compute a lifetime Vedic forecast across Vimshottari dasha periods.
Tier: All · Typical default response: ~10 KB.
Response shape
Returns: · headline: single-sentence summary the user can quote · facts.current — active mahadasha + antardasha + themes · facts.next_mahadashas — next 2-3 maha periods with themes · facts.sade_sati — phase + previous + next windows · facts.returns — Saturn / Jupiter / Rahu return cycles · facts.key_events — top 10 forecast events with age + year + description · facts.chart_ref — thread to subsequent tools Add `include=trajectories` for the per-area life-arc curves (LARGE, ~1.5 MB). Every other lifemap section — current, mahadashas, sade_sati, returns, key_events — already ships by default.
Sections · one call, not several
Ships by default — do not ask for these:
currentnext_mahadashassade_satireturnskey_eventsOpt-in — add with include (comma-separated):
life_eventsThe lifetime forecast-event list with fructification windows, each carrying its Raman tier.
trajectorieslargeThe per-domain journey curve, point by point. LARGE — 1.5 MB.
A section parameter sent without its include token is an error, not a no-op.
Input
skipmale · femaleen · hi · sa · ta · te · kn · bn0.5 · 0.8 · 1 · 2parashari · jaimini · kpkundali_milan
Compute Ashtakoota compatibility between two Vedic birth charts.
Tier: All · Typical default response: ~5 KB.
Response shape
Returns: · headline: total score + verdict + Mangal dosha summary · facts.total / facts.out_of / facts.verdict — Ashtakoota total (0-36) with verdict label · facts.kootas — dict keyed by koota name (varna, vashya, tara, yoni, graha_maitri, gana, bhakoot, nadi) · facts.doshas — Mangal / Nadi / Bhakoot status · facts.flags — notable warnings (bhakoot_0, mutual_mangal, etc.) · facts.chart_ref_groom / facts.chart_ref_bride — thread to subsequent calls Inputs are `groom: {birth_datetime, latitude, longitude}` and `bride: {birth_datetime, latitude, longitude}`. This tool does NOT take `include` — the per-koota classical analysis and the cross-chart block (`facts.cross_chart`, including `venus_jupiter_comparison`) are returned by default.
Input
skipen · hi · sa · ta · te · kn · bnparashari · jaimini · kpshubh_muhurat
Find auspicious time windows (muhurtha) for an event.
Tier: All · Typical default response: ~3 KB.
Response shape
Returns: · headline: count + dates of top windows · facts.event_type, facts.location, facts.range · facts.top_windows — 5-10 ranked windows with quality + factors + blockers
Input
skipen · hi · sa · ta · te · kn · bnparashari · jaimini · kppanchang
Compute the Vedic panchanga (five-limbed almanac) for any date, time, and location.
Tier: All · Typical response: ~4 KB.
Response shape
Returns for each of the five limbs (tithi, nakshatra, yoga, karana, vara): · Entity (id + localized name) · Quality, lord, pada as applicable · Remaining degrees until the limb changes · End time in local and UTC Also returns: · Sunrise and sunset (HH:MM local) · Rahu Kalam, Gulika Kalam, Yamaganda windows with active flag · Calendar: masa (with adhika/kshaya flags), samvatsara, Vikrama and Shaka year, ayana, ritu, and the next sankranti · Day yogas: anandadi yoga + the active dainika yogas (Sarvartha Siddhi, Amrita Siddhi, Ravi, Dagdha, etc.), each tier-tagged standard (Drik-Panchang set) or classical (extended) · Moon's rashi (Chandra rashi — the Vedic moon sign), localized · Eclipses: next solar + next lunar eclipse (grahana) — type, certainty, days away, and UTC date For birth chart panchanga, use `kundali` — its `panchanga` section carries `facts.panchanga` anchored to the birth moment.
Sections · one call, not several
Ships by default — do not ask for these:
calendarday_yogasinauspiciouseclipsesOpt-in — add with include (comma-separated):
windowsDay divisions: choghadiya (16), hora (24), and the brahma / abhijit / amrita / varjya / dur muhurtas. Was `include=detail` before 13.0.0.
A section parameter sent without its include token is an error, not a no-op.
Input
skipen · hi · sa · ta · te · kn · bnpramaan
Explain WHY a specific Jyotish claim is true for a chart — full reasoning chain with rule provenance and classical citations.
Tier: All · Typical default response: ~2-3 KB; include=trace adds ~3-8 KB; include=all adds ~10-30 KB.
Response shape
Returns: · content[0].text — explanatory prose · facts.claim, facts.supporting_factors[], facts.counter_evidence[] Opt-in via `include=`: · include=trace — the 6-stage Vivek provenance chain + per-factor (factor_type, participating_grahas, bhavas_involved, provenance) under detail. · include=detail — school_attribution + disputed_conclusions (the dedicated `schools` token was retired; this single-school artifact's doctrine is a detail-tier field now). · include=metrics — Shadbala strength_breakdown per relevant graha under detail. · include=all — every detail section above. Trace also expands the prose with a numbered 6-stage walkthrough. When relaying the answer, quote `facts.claim` and the factor descriptions. NOTE: this tool returns no classical locus of its own — `facts.supporting_factors[].id.id` is a `concept:` URI you can pass to `kundali`'s `classical_rules` section or to chat to obtain the citation.
Input
en · hi · sa · ta · te · kn · bnparashari · jaimini · kpchat
Open-ended Jyotish conversation grounded in citations from the classical canon (BPHS, Phaladeepika, Saravali, and curated commentaries). Birth data is OPTIONAL.
Tier: All · Typical response: 1-3 KB.
Response shape
Returns: · content[0].text: the full answer as prose (claim texts joined) · structuredContent.headline: first sentence of the answer (or an 'Answered with N citations' fallback when there is no prose) · structuredContent.classification: { tier: 'tier1'|'tier2'|'tier3', category, on_topic, specialty?, intent_kind } · structuredContent.claims: [{ text, status: 'sourced'|'interpretation', citations?: [{concept, display_label?, classical_locus?, passage?, source, relevance?}] }] — 'sourced' means the claim carried an inline citation marker that resolved against real grounding. IMPORTANT: on an LLM-GENERATED answer every claim is 'interpretation' BY DESIGN — the generator is instructed to write clean prose with no inline markers, because markers leaked into prose (Hindi, multi-word loci, truncated tokens) and, worse, were FORGEABLE: a model can attach a valid marker to an invented claim. 'sourced' is therefore reachable only on deterministic paths (the no-LLM knowledge fast path). Do NOT use per-claim status as your grounding signal on chart-anchored answers. Use the RESPONSE-level grounding instead: facts.citations[] and metadata.provenance{grounded, sources, route} — those are built from what was actually fed to the model, so they cannot be fabricated by it. · structuredContent.metadata: { validator_passed, thread_context_chars? } · structuredContent.facts.answered — false when needs_birth_data is true or there are no claims (e.g. a Tier-1 turn). · structuredContent.facts.citations? — the same citation shape as above, deduped by source across all claims (omitted when empty). THIS IS A GROUNDING SET, NOT EVIDENCE FOR THE ANSWER: it lists what the engine knew about this chart and question, which is exactly what makes it un-forgeable. Label it 'what the engine knew about your chart', never 'sources for this answer'. Rank it with two fields: `origin` ('question' = routed from the message or a tool the question triggered; 'chart' = a natal rule that fired regardless of what was asked — typically ~100 of them), then `relevance` (1.0 = this fired rule is anchored to a bhava the question is about, 0.0 = it is not, ABSENT = the question named no matchable subject, so treat it as unknown and rank on origin alone — absent is NOT zero). Nothing is dropped or rescored; cut the tail yourself if you want a short panel. · structuredContent.facts.needs_birth_data / .missing_fields? — the ask-back signal (missing_fields omitted when empty). · structuredContent.facts.time_known? — false when birth_datetime was date-only (no clock time supplied); omitted when no birth data was given at all. · structuredContent.facts.validator_issues? — present only when the safety scan flagged something (omitted when clean). · structuredContent._meta / _meta (result-level, identical): { tool: 'chat', classification_tier, api_version, engine, codename }
Input
male · femaleen · hi · sa · ta · te · kn · bnsubmit_feedback
Submit feedback on a chart / claim / explanation. Stored anonymously for engine improvement — no birth data is retained; the claim_id is the only correlator.
Tier: All · Typical response: <1 KB.
Response shape
Returns: · facts.acknowledged: true, facts.feedback_id
Input
accuracy · completeness · relevance · clarityget_version
Return engine + API version + protocol info. Unauthenticated — no API key required.
Tier: All (no auth required) · Typical response: <1 KB.
Response shape
Returns: · facts.engine_version, facts.api_version, facts.release_codename, facts.build
No input parameters.
Limits by tier.
Exceeding the per-minute limit or the monthly quota returns a JSON-RPC error with code -32029 and an explanatory message (the minute window resets automatically):
{"jsonrpc":"2.0","id":1,"error":{"code":-32029,
"message":"Rate limit exceeded: 600 requests/min for the Standard tier. See https://kundalimcp.com/pricing"}}Once a monthly quota is spent, Standard and High Traffic accounts with extra usage enabled keep serving (wallet-metered); Free Forever hard-caps until the UTC month rolls over.
JSON-RPC errors with hints.
Errors follow JSON-RPC 2.0. Every error carries a machine-readable code, a human-readable message, and — where applicable — data.hint with a self-correction suggestion for agents.
Agents should inspect data.hint before retrying. Supported datetime window: approximately 2000 BCE – 3000 CE (the analytic ephemeris validity range); out-of-range inputs return -32000.
Three calls to feel the product.
The shortest path from “I have a key” to “I just got real data about myself.” Run them in order; each grounds the next.
1 · Read today's panchanga
No birth data needed, instant result. panchang returns the five limbs (tithi, nakshatra, yoga, karana, vara), sunrise/sunset, and the Rahu Kalam / Gulika / Yamaganda windows for any date and location. The perfect first call to confirm your key works.
{
"jsonrpc": "2.0", "id": 1,
"method": "tools/call",
"params": {
"name": "panchang",
"arguments": {
"datetime": "2026-07-16T09:00:00",
"latitude": 28.6139,
"longitude": 77.2090,
"locale": "en"
}
}
}2 · Cast the chart
kundali with birth data returns the full ChartArtifact. Before quoting nakshatra-, pada-, or D9-based predictions, scan idl.boundary_margins: any graha with boundary_sensitive: true means the placement straddles a classical boundary and the agent should confirm exact birth time first.
{
"jsonrpc": "2.0", "id": 2,
"method": "tools/call",
"params": {
"name": "kundali",
"arguments": {
"birth_datetime": "1990-01-15T05:00:00",
"latitude": 28.6139,
"longitude": 77.2090,
"school": "parashari",
"locale": "en"
}
}
}3 · Read today's sky
The transits section of kundali overlays planetary positions on the natal chart — gochara, vedic aspects, Sade Sati phase — and ships by default, so this needs no include and no second call. The active dasha across all 5 levels with fraction elapsed arrives in the same response at facts.active_dasha. For ingresses, retrograde stations and returns across a window, add include=transit_events with transit_start and transit_end. Birth data is re-supplied each call — pass flat birth_datetime + latitude + longitude (recommended), or wrap them in a chart_ref object for legacy compatibility.
{
"jsonrpc": "2.0", "id": 3,
"method": "tools/call",
"params": {
"name": "kundali",
"arguments": {
"chart_ref": {
"birth_datetime": "1990-01-15T05:00:00",
"latitude": 28.6139,
"longitude": 77.2090
},
"transit_date": "2026-04-26",
"school": "parashari",
"locale": "en"
}
}
}Ready to wire in your agent?
Free compute tier — no credit card required. 9 tools, 7 languages, every rule source-cited — live at mcp.kundalimcp.com/mcp.