guide

What an astrology MCP server is and how to use it

An astrology MCP server lets AI assistants compute birth charts and run astrology queries through a standard tool protocol. Here is how Vedika's works and how to wire it in.

An astrology MCP server is a Model Context Protocol server that exposes astrology operations — chart computation, dasha timelines, transits, and natural-language readings — as structured tools an AI assistant can call directly. Instead of guessing where the planets were at a birth moment, the assistant invokes a real tool that computes the chart from an ephemeris and returns typed data. Vedika publishes one of the first public astrology MCP servers, npx @vedika-io/mcp-server, with 36 tools backed by the same API that powers production integrations.

Why astrology needs a tool layer, not just a prompt

Large language models are confident pattern matchers, which is exactly the wrong trait for ephemeris math. Ask an LLM agent to place the Moon for a 1987 Mumbai birth and it will produce a plausible-looking longitude that is quietly wrong by degrees. Degrees matter: a Moon that drifts across a sign boundary changes the Nakshatra, the dasha sequence, and every downstream interpretation. The Model Context Protocol fixes this by letting the model delegate the deterministic part to a server it can trust.

MCP is an open standard for connecting AI assistants to external tools and data. A server advertises a set of tools with JSON schemas; an MCP-compatible client or IDE discovers them and lets the model call them with validated arguments. For astrology this separation is the whole point: the model handles language and intent, while the server handles the astronomy and the sourcing.

What the server returns instead of a guess

When the model calls a chart tool, it gets back real planetary longitudes, house cusps, sign placements, and aspect data computed from the XALEN Ephemeris — Vedika's own open-source astronomical engine, published under Apache-2.0 on crates.io, PyPI, and npm. The engine carries roughly 2,200 tests and was validated against JPL DE440 and the reference swetest implementation, with no charts deviating beyond 0.1° across a five-million-chart sweep. That is astronomical precision for positions; it is not a claim about interpretive correctness, which is a separate concern handled by citation.

The 36 tools, grouped by what a developer actually does

The tool set maps onto the real tasks an assistant performs when a user asks an astrology question. Rather than memorize 21 names, think in four buckets.

Because every tool shares the same birth-details contract, an agent can chain them: geocode a city, compute the chart, pull the running dasha, then ask the query tool to interpret "career prospects in the current period" with all three already in context.

Wiring the server into an MCP client

Registration is a single config entry. The server runs over stdio via npx, so there is nothing to host yourself. Add it to your client's MCP configuration with your key in the environment:

npx -y @vedika-io/mcp-server

A typical MCP client configuration block looks like this:

{
  "mcpServers": {
    "vedika": {
      "command": "npx",
      "args": ["-y", "@vedika-io/mcp-server"],
      "env": {
        "VEDIKA_API_KEY": "vk_live_YOUR_API_KEY"
      }
    }
  }
}

Restart the client and the 36 tools appear in its tool list, ready for the model to call. The key is read from the environment and sent as x-api-key on every underlying request to https://api.vedika.io; it never has to appear in a prompt. If you want to explore the shapes before committing a key, point your own calls at the free sandbox, which mirrors the endpoints without authentication.

What a tool call resolves to under the hood

Each MCP tool is a thin wrapper over a documented HTTP endpoint, so you can reproduce any call without MCP at all. The interpretation tool maps to the main query endpoint:

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What does my chart say about career direction?",
    "birthDetails": {
      "datetime": "1990-08-15T14:30:00",
      "latitude": 19.0760,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
    },
    "speed": "fast"
  }'

The same request from a script, using a generic LLM-agnostic HTTP client, is just as direct:

import requests

resp = requests.post(
    "https://api.vedika.io/api/v1/astrology/query",
    headers={"x-api-key": "vk_live_YOUR_API_KEY"},
    json={
        "question": "Summarize the current dasha period for relationships.",
        "birthDetails": {
            "datetime": "1990-08-15T14:30:00",
            "latitude": 19.0760,
            "longitude": 72.8777,
            "timezone": "Asia/Kolkata",
        },
    },
)
reading = resp.json()

For pure computation without interpretation — say you only need the planetary table to render your own UI — the V2 endpoints under /v2/astrology/* take flat datetime, latitude, longitude, and timezone fields and return structured data. Streaming readings are available at /api/v1/astrology/query/stream over server-sent events when you want to render tokens as they arrive.

How it stays honest: ephemeris plus citations

An astrology tool can be wrong in two different ways, and the MCP server guards against both. Positional errors are handled by the XALEN Ephemeris, so the numbers are reproducible and traceable to a published engine. Interpretive errors — the more insidious kind — are handled by sourcing. Every astrological claim the query tool surfaces is attributable to classical texts that practitioners actually train from: Brihat Parashara Hora Shastra and Phaladeepika for Vedic, Krishnamurti's KP Readers for KP, Ptolemy's Tetrabiblos for Western, alongside Saravali, Jataka Parijata, and the Jaimini Sutras where relevant.

That matters for an agent builder. If your assistant cites a yoga or a house lordship, you want a real source behind it rather than a paraphrase the model absorbed from a blog. The tool layer keeps the model from inventing verse numbers or fabricating timing rules, which is the failure mode that erodes user trust on the first wrong reading.

One server, three systems, thirty languages

A recurring integration headache is that Vedic, Western, and KP usually live in separate products with separate keys and separate data shapes. The MCP server collapses that: the same tools accept a system parameter, so an agent can return a sidereal Vedic chart, a tropical Western chart, or a KP reading from one integration, and reach further into Jaimini, Tajaka, Lal Kitab, and numerology when a question calls for it. Responses are available across 30 languages, including 14 Indic languages, generated natively rather than machine-translated after the fact.

Underneath, the MCP tools sit on a surface of more than 600 API operations across 25 domains — 704 enumerated as of June 2026. The MCP server is the agent-friendly slice of that surface; when you outgrow it, the full REST API is right there with the same auth and the same data engine.

Where an MCP integration fits versus calling the API directly

Reach for the MCP server when an AI assistant or LLM agent is the one deciding what to compute — a chat product, an in-IDE helper, or an autonomous workflow that picks tools based on user intent. The protocol handles tool discovery and argument validation so you write less glue. Call the REST API directly when you control the orchestration yourself: a backend job, a report renderer, or a mobile app where you already know exactly which endpoint to hit. Both paths share auth, pricing, and the XALEN Ephemeris, so you can start with MCP and drop to raw HTTP for the hot paths without changing engines.

Key facts

Frequently asked questions

What is an astrology MCP server?

It is a Model Context Protocol server that exposes astrology operations as structured tools an AI assistant can call. Instead of hallucinating planetary positions, the assistant invokes a real tool that computes the chart from an ephemeris and returns typed data. Vedika ships one as npx @vedika-io/mcp-server with 36 tools spanning chart computation, dashas, transits, and natural-language queries.

How do I add the Vedika MCP server to my AI client?

Add a config entry that runs npx @vedika-io/mcp-server with your VEDIKA_API_KEY in the environment. Any MCP-compatible client or IDE discovers the tools automatically once the server is registered and the client restarts. See the docs for client-specific snippets.

Do I need a paid key to try the tools?

You can explore the same endpoint shapes against the free sandbox without a key. Live calls against production use a vk_live_ key tied to a plan; see pricing for the $12–$240/mo tiers and per-query rates.

Does the server make up planetary positions?

No. Positions come from the XALEN Ephemeris, validated against JPL DE440 and swetest, and interpretations are attributed to classical sources rather than fabricated.

Build on the Vedika astrology API

700+ operations, Vedic + Western + KP, 30 languages, an open-source XALEN ephemeris, and a built-in LLM. Free sandbox — no signup.

Try the free sandbox