Astronest Quickstart MCP Server

AstroNest: Vedic astrology for apps and AI agents

AstroNest is a Vedic astrology (Jyotiṣa) engine you can call as a REST API or connect to an AI agent over MCP. It computes on its own JPL DE440 ephemeris. The chart, periods and the readings (interpret, guidance, compatibility, guna milan) are deterministic: the same birth data always gives the same answer, with the reasons behind each reading. Only forecast and timing are worded by a language model, and they say so.

This repository has two things: how to connect AstroNest to an AI agent, and a Next.js quickstart on the REST API.

• Docs: https://www.astronest.ai/developers
• OpenAPI 3.1 spec: https://www.astronest.ai/openapi/astronest-v1.json
• Postman: AstroNest Developer API workspace
• Keys: https://www.astronest.ai/developer. Sandbox keys are free and return fixed samples.
• Guides: Kundli API · Guna Milan API · Muhūrta API · Praśna API · Ephemeris API · Astrology MCP server
• For LLMs: https://www.astronest.ai/llms.txt

Connect it to an AI agent (MCP)

Endpoint (Streamable HTTP): https://www.astronest.ai/api/developer/mcp

Claude Code

claude mcp add --transport http astronest https://www.astronest.ai/api/developer/mcp \
  --header "Authorization: Bearer YOUR_ASTRONEST_KEY"

mcp.json (Cursor, VS Code and other clients that read this format)

{
  "mcpServers": {
    "astronest": {
      "url": "https://www.astronest.ai/api/developer/mcp",
      "headers": { "Authorization": "Bearer YOUR_ASTRONEST_KEY" }
    }
  }
}

Also on Smithery and the MCP Registry as io.github.onedotlinks/astronest.

What an agent can ask it

Each tool answers one question. The interpretive ones read the chart the way a practitioner does and return the reasons, not just positions:

The readings describe what the chart shows and why. They are symbolic interpretation, not predictions, and not medical, legal, financial or psychological advice; every response carries that disclaimer.

The Next.js quickstart

A small Next.js app on the AstroNest Developer API. Enter a birth date, time and place and get:

• the chart: lagna, the nine grahas with sign, house, nakṣatra and dignity, and the running daśā (1 credit)
• guidance now: plain-language cards for the running mahādaśā / antardaśā / pratyantardaśā (3 credits)
• a domain reading: career, marriage, finance and twelve more, with supporting factors, cautions, timing windows and how many methods agree (5 credits)
• optionally, "explain in plain words" with your own LLM (0 AstroNest credits)

None of the three AstroNest calls uses a language model. They are deterministic, so they return in seconds and the same input always gives the same answer.

Run it in five minutes

1. Get a key. Sign in at https://www.astronest.ai/developer and create a key. Every account gets 100 free live credits once, valid for 60 days from your first live key (they do not renew): enough for about 20 domain readings or 100 charts. Sandbox keys are free with no time limit and return fixed sample responses. When the free credits are used, or after 60 days, live calls return 402 credits_exhausted until you buy a credit pack; sandbox keys keep working.
2. Install and configure.

   npm install
   cp .env.example .env.local
   # put your key in ASTRONEST_API_KEY
   

3. Run.

   npm run dev
   

   Open http://localhost:3000.

How it fits together

browser ──► /api/astronest/{chart|guidance|interpret} ──► AstroNest API   (your key, server-side)
        └─► /api/explain ──────────────────────────────► your LLM         (optional)

• lib/astronest.ts is a typed client. It is the file to copy into your own app.
• app/api/astronest/[op]/route.ts forwards only those three operations, so the route can't be used to call every endpoint your key allows.
• app/api/explain/route.ts sends the reading AstroNest computed to any OpenAI-compatible chat-completions endpoint (OpenAI, Vercel AI Gateway, OpenRouter, a local Ollama) and tells the model to use only the facts it was given. Your model writes the words; AstroNest does the astrology.

Before you deploy

• Your key is a secret. It lives in server environment variables only. Never prefix it with NEXT_PUBLIC_, and never call the API from the browser. The API sends no CORS headers, so browser calls fail anyway.
• The demo routes spend your credits for anyone who calls them. By default they answer only on localhost. Put your own sign-in (and ideally a rate limit) in front of them before you set ALLOW_PUBLIC_DEMO=true. The localhost check reads the request host, so don't rely on it behind a proxy that rewrites Host.
• Birth data is personal data. This app stores nothing, and the API stores nothing either. If you add storage, you take on the data-protection duties that come with it.
• Show the disclaimer that comes with every response: symbolic interpretation, not medical, legal, financial or psychological advice.

Going further

The four single-moment Ephemeris calls cost 0.1 credit each: 1 credit per started block of 10, counted across them per account (the call that opens a block reports units_charged: 1, the next nine report 0). Only successful (2xx) calls are charged. When credits run out, the API returns 402 credits_exhausted; buy a pack in the developer portal. Paid credits do not expire.

• OpenAPI 3.1 spec: https://www.astronest.ai/openapi/astronest-v1.json (import it into Postman, or generate a client in any language)
• Reference: the developer portal at https://www.astronest.ai/developer