Connect
One line in Claude Code, a few in any other client
claude mcp add --transport http astronest https://www.astronest.ai/api/developer/mcp \ --header "Authorization: Bearer YOUR_ASTRONEST_KEY"
{
"mcpServers": {
"astronest": {
"url": "https://www.astronest.ai/api/developer/mcp",
"headers": {
"Authorization": "Bearer YOUR_ASTRONEST_KEY"
}
}
}
}All 21 endpoints are tools. Full setup, including clients without remote MCP support: MCP server guide. Below, two of the tools as REST calls with their real responses.
POST /v1/chart · 1 credit
Natal chart (kundli)
Sidereal chart: ascendant, the nine grahas, twelve houses, yogas and the life-period (daśā) timeline. A modern Western block is added unless `western` is false. With `location`, also astrocartography lines at that place and the chart's own frame relocated there. Includes two classical sub-charts by default; ask for any of the others with `divisionals`.
Request (works as-is with a sandbox key):
curl -X POST https://www.astronest.ai/api/developer/v1/chart \
-H "Authorization: Bearer astro_sandbox_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}'Response (sandbox sample, long lists shortened):
{
"requestId": "7d2e2084-f70d-4981-ab40-2e726d8fbbfc",
"engineVersion": "astro-nest-v1-public",
"timestamp": "2026-10-06T17:02:35.084Z",
"usage": {
"units_charged": 1,
"remaining_credits": 95
},
"disclaimer": "Symbolic interpretation only. Not medical, legal, financial, or psychological advice.",
"domain": "core_chart",
"computationId": "b029fba85c47c76de90d4e1dce1436149cb7471d09c93ceff7eeb6d26e494825",
"ascendant": {
"sign": "Virgo",
"degree": 0.4042,
"nakshatra": "Uttara Phalguni",
"pada": 2
},
"planets": [
{
"planet": "Sun",
"sign": "Aries",
"house": 8,
"degree": 27.6589,
"longitude": 27.6589,
"retrograde": false,
"nakshatra": "Krittika",
"pada": 1,
"dignity": "exalted",
"combust": null,
"combustion": null
},
{
"planet": "Moon",
"sign": "Scorpio",
"house": 3,
"degree": 25.6775,
"longitude": 235.6775,
"retrograde": false,
"nakshatra": "Jyeshtha",
"pada": 3,
"dignity": "debilitated",
"combust": false,
"combustion": null
},
{
"planet": "Mars",
"sign": "Aquarius",
"house": 6,
"degree": 22.2881,
"longitude": 322.2881,
"retrograde": false,
"nakshatra": "Purva Bhadrapada",
"pada": 1,
"dignity": "neutral",
"combust": false,
"combustion": null
},
"… 9 more"
],
"houses": [
{
"house": 1,
"sign": "Virgo",
"degree": 0,
"lord": "Mercury"
},
{
"house": 2,
"sign": "Libra",
"degree": 0,
"lord": "Venus"
},
{
"house": 3,
"sign": "Scorpio",
"degree": 0,
"lord": "Mars"
},
"… 9 more"
],
"aspects": [
{
"planet1": "Sun",
"planet2": "Mars",
"type": "sextile",
"orb": 5.37,
"applying": false
},
{
"planet1": "Sun",
"planet2": "Saturn",
"type": "trine",
"orb": 3.91,
"applying": true
},
{
"planet1": "Sun",
"planet2": "Neptune",
"type": "trine",
"orb": 6.99,
"applying": false
},
"… 26 more"
],
"yogas": [
{
"name": "ViparitaRajYoga",
"englishName": "Reversal Combination — unexpected rise",
"type": "viparita_raj_yoga",
"planets": [
"Mars",
"Sun"
],
"houses": [
6,
8
],
"strength": null,
"basis": "Sarala — Mars (8th lord) in the 6th; Vimala — Sun (12th lord) in the 8th",
"classicalSource": "BPHS Chapter 35"
},
{
"name": "MalavyaYoga",
"englishName": "Malavya Combination — beauty and refinement",
"type": "pancha_mahapurusha",
"planets": [
"Venus"
],
"houses": [
7
],
"strength": null,
"basis": "Venus in Pisces (7th house) — exalted/own sign in kendra",
"classicalSource": "BPHS Chapter 34"
},
{
"name": "BudhaAdityaYoga",
"englishName": "Sun-Mercury Combination — intelligence and communication",
"type": "special_yoga",
"planets": [
"Sun",
"Mercury"
],
"houses": [
8,
8
],
"strength": null,
"basis": "Mercury 12.6° from Sun in Aries — clear BudhaAditya",
"classicalSource": "BPHS Chapter 37"
},
"… 4 more"
],
"dasha": {
"current": {
"mahadasha": "Sun",
"mahadashaEnd": "2028-11-14T06:46:15.504Z",
"antardasha": "Mercury",
"antardashaEnd": "2027-07-10T04:54:50.304Z",
"pratyantardasha": "Mercury",
"pratyantardashaEnd": "2026-10-16T17:31:04.074Z"
},
"timeline": [
{
"planet": "Mercury",
"start": "1990-05-12T09:04:59.999Z",
"end": "1995-11-15T06:42:39.504Z",
"level": "mahadasha",
"antardashas": [
"{…}",
"{…}",
"{…}"
]
},
{
"planet": "Ketu",
"start": "1995-11-15T06:42:39.504Z",
"end": "2002-11-14T23:27:03.504Z",
"level": "mahadasha",
"antardashas": [
"{…}",
"{…}",
"{…}",
"… 6 more"
]
},
{
"planet": "Venus",
"start": "2002-11-14T23:27:03.504Z",
"end": "2022-11-14T19:51:03.504Z",
"level": "mahadasha",
"antardashas": [
"{…}",
"{…}",
"{…}",
"… 6 more"
]
},
"… 7 more"
]
},
"divisionals": [
{
"division": "D9",
"ascendant": {
"sign": "Capricorn",
"degree": 0.4042
},
"planets": [
{
"planet": "Sun",
"sign": "Sagittarius",
"house": 12,
"degree": 0.9922,
"longitude": 240.9922,
"retrograde": false,
"nakshatra": null,
"pada": null,
"dignity": null
},
{
"planet": "Moon",
"sign": "Aquarius",
"house": 2,
"degree": 2.3442,
"longitude": 302.3442,
"retrograde": false,
"nakshatra": null,
"pada": null,
"dignity": null
},
{
"planet": "Mars",
"sign": "Aries",
"house": 4,
"degree": 2.2881,
"longitude": 2.2881,
"retrograde": false,
"nakshatra": null,
"pada": null,
"dignity": null
},
"… 9 more"
]
},
{
"division": "D10",
"ascendant": {
"sign": "Taurus",
"degree": 0.4042
},
"planets": [
{
"planet": "Sun",
"sign": "Capricorn",
"house": 9,
"degree": 0.6589,
"longitude": 270.6589,
"retrograde": false,
"nakshatra": null,
"pada": null,
"dignity": null
},
{
"planet": "Moon",
"sign": "Pisces",
"house": 11,
"degree": 1.6775,
"longitude": 331.6775,
"retrograde": false,
"nakshatra": null,
"pada": null,
"dignity": null
},
{
"planet": "Mars",
"sign": "Virgo",
"house": 5,
"degree": 1.2881,
"longitude": 151.2881,
"retrograde": false,
"nakshatra": null,
"pada": null,
"dignity": null
},
"… 9 more"
]
}
],
"western": {
"tradition": "western",
"classical": false,
"notice": "Modern Western techniques, published alongside the Jyotisa engine and NOT part of it. These are not classical sastra, carry no corpus provenance, and are never used to reach a verdict on any AstroNest surface. Western natural-benefic/malefi…",
"aspectMesh": {
"source": "aspects",
"note": "The `aspects` array on this response is the five Ptolemaic majors (conjunction, opposition, trine, square, sextile) measured by DEGREE with orbs. That is a Western construction and is named here because it ships inside the Jyotisa payload. …"
},
"tropical": {
"ayanamsa": "lahiri",
"ayanamsaDegrees": 23.7224,
"note": "Tropical longitude = sidereal longitude + ayanamsa, at this chart’s epoch. The Jyotisa payload is SIDEREAL throughout; nothing here changes it.",
"positions": [
{
"planet": "Sun",
"longitude": 51.3813,
"sign": "Taurus",
"degree": 21.3813,
"retrograde": false
},
{
"planet": "Moon",
"longitude": 259.4,
"sign": "Sagittarius",
"degree": 19.4,
"retrograde": false
},
{
"planet": "Mars",
"longitude": 346.0105,
"sign": "Pisces",
"degree": 16.0105,
"retrograde": false
},
"… 9 more"
]
},
"outerPlanets": [
{
"planet": "Uranus",
"sign": "Sagittarius",
"house": 4,
"degree": 15.5317,
"signification": "sudden change, disruption, awakening, independence",
"note": "Generational by sign and read by house and aspect. Carries NO classical dignity — the absent dignity field is by design, not a gap."
},
{
"planet": "Neptune",
"sign": "Sagittarius",
"house": 4,
"degree": 20.671,
"signification": "dissolution, imagination, spirituality, illusion",
"note": "Generational by sign and read by house and aspect. Carries NO classical dignity — the absent dignity field is by design, not a gap."
},
{
"planet": "Pluto",
"sign": "Libra",
"house": 2,
"degree": 22.5287,
"signification": "transformation, power, regeneration through upheaval",
"note": "Generational by sign and read by house and aspect. Carries NO classical dignity — the absent dignity field is by design, not a gap."
}
],
"astrocartography": {
"notice": "Astrocartography lines are absolute earth positions, not bearings from where the native lives: “east of here” is a compass illusion. MC and IC lines are meridians and do not depend on observer latitude. ASC and DSC lines are curves whose lo…",
"computed": true,
"meridians": [
{
"planet": "Sun",
"angle": "MC",
"geoLongitude": 42.8282,
"meaning": "career and public standing"
},
{
"planet": "Sun",
"angle": "IC",
"geoLongitude": -137.1718,
"meaning": "home, roots and private life"
},
{
"planet": "Moon",
"angle": "MC",
"geoLongitude": -107.6554,
"meaning": "career and public standing"
},
"… 21 more"
],
"atLocation": null
}
}
}Every field: /v1/chart in the reference.
POST /v1/guna-milan · 2 credits
Guna Milan (36-point Aṣṭakūṭa) and Manglik
The classical Aṣṭakūṭa match for a pair (all eight kūṭas, with the Bhakoot and Nāḍī doṣas) and Manglik for both charts reckoned from the lagna, the Moon and Venus, with mutual cancellation. The same engine as /v1/compatibility, without the full reading: the score is one input, and /v1/compatibility reads each chart's marital promise, timing and doṣas on top of it. Deterministic, no language model.
Request (works as-is with a sandbox key):
curl -X POST https://www.astronest.ai/api/developer/v1/guna-milan \
-H "Authorization: Bearer astro_sandbox_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"a":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209,"name":"A"},"b":{"date":"1991-11-03","time":"06:10","timezone":"Asia/Kolkata","latitude":19.076,"longitude":72.8777,"name":"B"}}'Response (sandbox sample, long lists shortened):
{
"requestId": "sandbox",
"engineVersion": "astro-nest-v1-public",
"timestamp": "2026-10-11T19:44:27.900Z",
"domain": "guna_milan",
"usage": {
"units_charged": 0,
"remaining_credits": 0
},
"disclaimer": "Symbolic interpretation only. Not medical, legal, financial, or psychological advice.",
"partners": {
"a": {
"name": "A",
"birth": "1990-05-12 · 14:35",
"moonNakshatra": "Jyeshtha",
"moonSign": "Scorpio"
},
"b": {
"name": "B",
"birth": "1991-11-03 · 06:10",
"moonNakshatra": "Uttara Phalguni",
"moonSign": "Virgo"
}
},
"roles": {
"groom": "a",
"bride": "b",
"basis": "No genders given: A is read as the groom and B as the bride (Varṇa is counted from the groom). Send gender to set it."
},
"gunaMilan": {
"totalGunas": 17.5,
"kutas": [
{
"name": "Varna",
"score": 1,
"max": 1,
"note": "Moon signs by element — groom water, bride earth. The classical ordering is satisfied (1). This kūṭa grades the Moon signs by element; it says nothing about either person’s community, and must not be presented as if it did."
},
{
"name": "Vashya",
"score": 1,
"max": 2,
"note": "Keeta / Manava (whole-sign group approximation)."
},
{
"name": "Tara",
"score": 1.5,
"max": 3,
"note": "remainders 7/4 — one auspicious."
},
"… 5 more"
],
"bhakootDosha": {
"present": false,
"cancelled": false,
"reason": null
},
"nadiDosha": {
"present": true,
"cancelled": false,
"reason": "Nāḍī dosha — both in Adi nāḍī (the gravest kūṭa; bears on progeny + health of the bond)."
},
"interpretation": "17.5/36 — a weak numerical match. This is ONE input (necessary, not sufficient): the promise, sustainability and happiness layers govern the final read and can override it. Nāḍī dosha stands — treat with weight."
},
"manglik": {
"a": {
"present": false,
"strength": "none",
"mitigations": [],
"cancelledBy": [
{
"rule": "Mars in Aquarius does not create the doṣa",
"sources": [
"How to Judge a Horoscope Vol 2 (B V Raman)",
"Marriage and Children Lessons"
]
}
],
"note": "NOT Manglik. Mars would carry the doṣa from Moon and Venus (reckoned from lagna 6th — clean; Moon 4th — carries; Venus 12th — carries), but it is cancelled: Mars in Aquarius does not create the doṣa (How to Judge a Horoscope Vol 2 (B V Rama…",
"reckonings": [
{
"from": "lagna",
"house": 6,
"present": false,
"strength": "none"
},
{
"from": "Moon",
"house": 4,
"present": true,
"strength": "strong"
},
{
"from": "Venus",
"house": 12,
"present": true,
"strength": "strong"
}
]
},
"b": {
"present": true,
"strength": "strong",
"mitigations": [],
"cancelledBy": [],
"note": "Mars carries the doṣa from lagna and Moon (Mars in Libra) — Manglik doṣa (reckoned from lagna 1st — carries; Moon 2nd — carries; Venus 3rd — clean). Softened, not cancelled: Jupiter aspects the 7th (Predictive Astrology Part I; Bhasin). Som…",
"reckonings": [
{
"from": "lagna",
"house": 1,
"present": true,
"strength": "strong"
},
{
"from": "Moon",
"house": 2,
"present": true,
"strength": "partial"
},
{
"from": "Venus",
"house": 3,
"present": false,
"strength": "none"
}
]
},
"cancelled": false,
"reason": "Chart B is Manglik and the partner is not — the dosha stands and must be weighed for the union's longevity.",
"points": {
"variation": 5.1,
"balanced": false,
"heavier": "B",
"note": "Kuja points (Raman's table, Trivedi's method; from the lagna): A 25, B 152.5 — variation 510%; beyond 25%: unbalanced, Chart B carries more. A comparison to weigh, not a cancellation."
},
"pointsTotals": {
"a": 25,
"b": 152.5
}
},
"note": "The 36-point score is one input, not the verdict. /v1/compatibility reads each chart's marital promise, timing and doshas on top of it."
}Every field: /v1/guna-milan in the reference.
Why AstroNest
Deterministic interpretation
Interpret, guidance, compatibility and guna milan call no language model: the same chart always gets the same reading. Only forecast and timing are voiced by a model, and they are marked as such.
Readings grounded in classical Vedic methodology
Interpretation applies classical rules, and each reading names the classical texts it is grounded in.
Nothing silently missing
Every reading declares each of its layers as present, computed_empty, not_covered or failed, so an absent field is never left to guesswork.
Pricing
Sandbox keys are free, with no time limit, and return the samples above. A live key starts with 100 free credits; after that you buy credit packs. Each endpoint's cost in credits is shown above. Pricing
Questions
- How do I connect it to Claude or ChatGPT?
- Add https://www.astronest.ai/api/developer/mcp as a custom connector. The first tool call opens AstroNest sign-in: sign in, choose Sandbox (free fixed samples) or Live (real results, billed to your credits), and allow. There is no key to copy.
- Which clients work?
- Any client with remote MCP support: Claude, ChatGPT, Claude Code, Cursor, VS Code and others. Clients without sign-in support send an API key in the Authorization header; older clients can use mcp-remote.
- How is it billed?
- Each tool call costs the same credits as the REST endpoint behind it. Sandbox keys are free and return samples.
- Can I cap what an agent spends?
- Yes. Set a monthly credit limit when you approve a Live connection, or give the agent its own key with a limit.
- How do I disconnect an app?
- In the developer portal, under Connected apps, choose Disconnect. The app loses access at once. Removing the connector in the app also stops it.
Readings are symbolic interpretation, not medical, legal, financial or psychological advice.
More from the API