Developers
Use Astratva from your AI assistant
Astratva runs a Model Context Protocol (MCP) server. Connect Claude, Cursor, VS Code or another MCP client to it, and the assistant can work out a Panchang, a daily horoscope, transits, a birth chart or a compatibility match itself, from the same calculations as the website and the REST API.
Server URL
https://astratva.com/mcp
Streamable HTTP. Every answer is a plain JSON response; there is no session to keep and no event stream.
What you can ask
Once connected, ask in your own words. The assistant finds the place, calls the right tool and explains the result. For example:
- “What is the tithi in Madurai today, and when is Rahu Kalam?”
- “Make my birth chart: 17 May 1990, 04:17, Bengaluru. Which nakshatra is my Moon in, and which dasha am I in?”
- “Check the compatibility of these two birth details and explain the Guna Milan score.”
- “Which planets change sign or turn retrograde in the next two weeks?”
- “Plan my week in Chennai: I am Mesha rashi.”
- “How many API units do I have left this month?”
Your API key
The calculation tools run on your API plan, with the same keys as the REST API. Create a key on your developer page and have your client send it on every request:
Authorization: Bearer YOUR_API_KEY
There is no OAuth sign-in yet, only API keys. search-places works without a key; get-account works with any valid key, with or without a plan.
Connect
Replace YOUR_API_KEY with your key. Config file locations and formats change between versions, so check your client's MCP documentation if one of these does not load.
Claude Code
claude mcp add --transport http astratva https://astratva.com/mcp --header "Authorization: Bearer YOUR_API_KEY"Then run /mcp in Claude Code to see the server and its tools.
Cursor
In ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"astratva": {
"url": "https://astratva.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}VS Code
In .vscode/mcp.json. VS Code asks for the key once and stores it, so it is not written in the file:
{
"inputs": [
{
"type": "promptString",
"id": "astratva-key",
"description": "Astratva API key",
"password": true
}
],
"servers": {
"astratva": {
"type": "http",
"url": "https://astratva.com/mcp",
"headers": {
"Authorization": "Bearer ${input:astratva-key}"
}
}
}
}Claude Desktop
Claude Desktop's custom connectors sign in with OAuth, which Astratva does not offer yet. Its config file (claude_desktop_config.json, under Settings, Developer, Edit Config) can start mcp-remote, which connects to the server with your key. It needs Node.js.
{
"mcpServers": {
"astratva": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://astratva.com/mcp",
"--header",
"Authorization:${ASTRATVA_AUTH}"
],
"env": {
"ASTRATVA_AUTH": "Bearer YOUR_API_KEY"
}
}
}
}Restart Claude Desktop after saving.
Any HTTP client
MCP is JSON-RPC over HTTP POST. This calls get-account, which checks your key and costs nothing:
curl https://astratva.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-account","arguments":{}}}'Test with the MCP Inspector
The MCP Inspector lists the tools and prompts and lets you call them by hand. Start it with Node.js:
npx @modelcontextprotocol/inspectorIn the page it opens, choose the Streamable HTTP transport, enter https://astratva.com/mcp, add the header Authorization with the value Bearer YOUR_API_KEY, and connect.
Tools
A paid tool is the REST endpoint beside it, run on your key: the same abilities, plan check, rate limit and data. Each call costs that endpoint's units of your monthly allowance and shows in your usage like a REST call. A call that ends in an error costs nothing.
| Tool | What it does | Cost |
|---|---|---|
search-places |
Find a town or city in Astratva's gazetteer by name (names and aliases, in any of its scripts) and get up to 10 places with id, slug, name, region, country code, latitude, longitude and time zone. Call this first whenever the person names a place, then pass the id (or slug) as place to the other tools. Free; no API key needed. Example: {"query": "Madurai"}. | Free |
get-account |
Your Astratva API account: the plan, this month's allowance (units used, left, and when it resets), rate limit, the abilities of this API key, and links to manage keys and plans. Free (no units) and works without a plan, so call it when a tool answers needs_api_plan, missing_ability or allowance_exhausted. Needs an API key. | Free |
get-panchang |
The Panchang of one day at a place: vara, tithi, nakshatra, yoga and karana (each with the time it ends), paksha, sunrise, sunset, moonrise, moonset, Rahu Kalam, Yamagandam, Gulika Kalam and Abhijit. Times are local to the place. Give place (an id or slug from search-places) or lat, lon and tz. Example: {"place": "chennai-tamil-nadu-india", "date": "2026-11-12"}. Needs an API key and plan; costs 1 unit.
REST: GET /api/v1/panchang
|
Paid plan 1 unit |
get-panchang-month |
A month of Panchang at a place, one entry per day: sunrise (Unix time), the tithi number at sunrise (1-30) and the next one when it changes that day, and the nakshatra. For one day in full, use get-panchang. Give place (an id or slug from search-places) or lat, lon and tz. Example: {"place": "madurai-tamil-nadu-india", "year": 2026, "month": 11}. Needs an API key and plan; costs 1 unit.
REST: GET /api/v1/panchang/month
|
Paid plan 1 unit |
get-daily-horoscope |
The daily horoscope for a Moon sign (rashi): Gochara, where each graha is counted from the Moon sign on that day in India, with the leading theme and how many grahas are in favourable places. Example: {"sign": "mesha", "language": "hi"}. Needs an API key and plan; costs 1 unit.
REST: GET /api/v1/horoscope/{sign}
|
Paid plan 1 unit |
get-transits |
Where the nine grahas are at a moment (sidereal): sign (1-12), degree in the sign, nakshatra and pada, speed and whether retrograde. The moment is a local date and time in a time zone (default 06:00 in Asia/Kolkata). Example: {"date": "2026-11-12", "time": "09:30", "tz": "Asia/Kolkata"}. Needs an API key and plan; costs 1 unit.
REST: GET /api/v1/transits
|
Paid plan 1 unit |
get-transit-calendar |
Transit events in a window of days from a date: each graha entering a new sign (ingress, from and to sign numbers) and turning retrograde or direct (stations), with the time in India (Asia/Kolkata). Example: {"from": "2026-11-12", "days": 7}. Needs an API key and plan; costs 1 unit.
REST: GET /api/v1/transits/calendar
|
Paid plan 1 unit |
create-birth-chart |
A Vedic birth chart (sidereal, whole-sign houses): lagna, the nine grahas with sign, house, degree, nakshatra and pada, the twelve houses, navamsa (D9) and the Vimshottari dasha periods. Birth date and time are local to the birth place. Give place (an id or slug from search-places) or lat, lon and tz. Nothing is stored. Example: {"date": "1990-05-17", "time": "04:17", "place": "bengaluru-karnataka-india"}. Needs an API key and plan; costs 1 unit.
REST: POST /api/v1/charts
|
Paid plan 1 unit |
check-compatibility |
Marriage compatibility from two birth charts: Guna Milan (Ashtakoota, points out of 36, each koota) and the South Indian Porutham (matches out of 10). bride and groom each take date, time (local) and place (an id or slug from search-places) or lat, lon and tz. Nothing is stored. Example: {"bride": {"date": "1992-03-14", "time": "09:20", "place": "chennai-tamil-nadu-india"}, "groom": {"date": "1990-07-02", "time": "18:05", "place": "madurai-tamil-nadu-india"}}. Needs an API key and plan; costs 1 unit.
REST: POST /api/v1/compatibility
|
Paid plan 1 unit |
Every tool is read-only: charts and compatibility checks are calculated and not stored. Where the REST endpoint supports it, a tool takes language (en, hi, ta or te). Results carry meta.provenance, as REST answers do. The server also offers the resource astratva://methods: the zodiac, ayanamsha and house system behind every number.
Prompts
Ready-made instructions your client can offer you (in Claude Code, as slash commands). Each tells the assistant which tools to call, in what order, and how to explain the result. The prompt itself costs nothing; the tools it calls are charged as usual.
explain-birth-chart
Calculate a Vedic birth chart and explain it in plain words: lagna, Moon sign and nakshatra, the current dasha and notable placements, citing the chart facts. Uses search-places and create-birth-chart (1 unit).
birth_date: Birth date, YYYY-MM-DD.birth_time: Local birth time, HH:MM (24-hour).birth_place: Birth town or city, e.g. "Chennai, India".focus(optional): Optional theme to dwell on, e.g. "career" or "relationships".
daily-panchang-brief
A short planning brief from the day's Panchang at a place: tithi, nakshatra, yoga, karana, sunrise and sunset, Rahu Kalam and the other periods. Uses search-places and get-panchang (1 unit).
place: Town or city, e.g. "Madurai".date(optional): The day, YYYY-MM-DD. Default: today at the place.
compatibility-report
A balanced marriage compatibility report for two people: the Guna Milan score out of 36 and the Porutham matches, with the main factors explained. Uses search-places and check-compatibility (1 unit).
bride_birth_date: The bride's birth date, YYYY-MM-DD.bride_birth_time: The bride's local birth time, HH:MM (24-hour).bride_birth_place: The bride's birth town or city.groom_birth_date: The groom's birth date, YYYY-MM-DD.groom_birth_time: The groom's local birth time, HH:MM (24-hour).groom_birth_place: The groom's birth town or city.
plan-my-week
A summary of the next 7 days for planning: transit events, the daily horoscope for the Moon sign, and each day's Panchang at a place. Give a Moon sign, or birth details to find it. Uses get-transit-calendar, get-daily-horoscope, get-panchang (and create-birth-chart); about 10 units.
place: Where the person is this week (town or city), for local Panchang times.moon_sign(optional): Moon sign (rashi), e.g. "mesha" or "aries". Or give the birth details instead.birth_date(optional): Birth date, YYYY-MM-DD, when the Moon sign is not known.birth_time(optional): Local birth time, HH:MM, with birth_date.birth_place(optional): Birth town or city, with birth_date.
Plans
MCP has no plan of its own: it uses your API plan, its monthly units and its rate limit, shared with your REST calls. There is no free API tier, but search-places and get-account are free.
Errors
A tool that cannot answer returns a tool error (isError: true, still HTTP 200) with structuredContent.error: a stable code, a message, and links or details where they help. Assistants read the message, so most will tell you what to do.
| Code | What happened | What to do |
|---|---|---|
authentication_required |
The tool needs an API key and none was sent. | Add the Authorization header to your client's configuration (see Connect). |
invalid_api_key |
The key is unknown, revoked, expired or suspended, or your IP address is not on the key's allow list. | Check the key on your developer page, or create a new one. |
missing_ability |
The key exists but lacks the ability this tool needs. The error lists the abilities. | Create a key with those abilities on your developer page. |
needs_api_plan |
Your account has no active API plan. | Choose a plan; the error carries plans_url. |
allowance_exhausted |
This month's units are used up. | Wait for the new month (00:00 UTC on the 1st) or move to a larger plan; the error carries dashboard_url. |
rate_limited |
Too many calls a minute: your plan's rate, or search-places' 60 a minute per IP address. | Wait for retry_after_seconds, then call again. |
invalid_input |
An argument was refused. fields names each one and why. | Correct the arguments. Nothing is charged. |
place_not_found |
The place id or slug is not in the gazetteer. | Call search-places and use the id it returns. Nothing is charged. |
unavailable |
Something failed on Astratva's side. The error carries a request_id. | Try again later. If it keeps failing, contact support with the request_id. |
Two refusals come before any tool runs: more than 600 requests a minute from one IP address (REST and MCP together) get HTTP 429, and a prompt with invalid arguments gets the JSON-RPC error -32602.
Questions
- I entered a wrong key, but the tools still show up. Why?
- The key is checked when a tool needs it, not when the client connects. A wrong key still connects and lists the tools, and
search-placesstill works. To check a key, callget-account(ask your assistant “Check my Astratva account”): a wrong key answersinvalid_api_key, a good one shows your plan and the units left. - Do I need a separate plan for MCP?
- No. The same plan, keys and monthly units serve both the REST API and MCP. A tool call costs exactly what its REST endpoint costs, and your developer page counts them together.
- Can I use it from claude.ai or ChatGPT?
- Not yet. Their custom connectors sign in with OAuth, and Astratva's server has no OAuth, only API keys. Use a client that can send a header: Claude Code, Cursor, VS Code, or Claude Desktop with
mcp-remote. - Is the birth data I give my assistant stored?
- Not by Astratva. Birth details are used for the calculation and not stored, as with the REST API. Your assistant and its provider have their own rules for what you type.
- Which zodiac and ayanamsha?
- Sidereal, with the Lahiri ayanamsha, from precise astronomical calculation. Every result's
meta.provenancerecords the settings used. - Are the answers predictions?
- They are calculations from the tradition. The server asks assistants to present them plainly and without fatalism, but what the assistant writes is its own.
- Where is the full reference?
- Each tool's input and data match its REST endpoint, documented in the API reference. The developer overview explains errors, provenance and what is charged.
- Something does not work. Who do I ask?
- Contact us with the tool, the time and, for an
unavailableerror, itsrequest_id. Never send your API key.