A Vedic astronomy engine your agent can call.
Swiss Ephemeris positions, dashas, yogas, strengths and transits — exposed as 30 typed MCP tools over one HTTP endpoint. Point any MCP client at it and try it without a key, or sign in with Google for a free key with its own credit balance.
Connect, then compute once and read many times
Birthstar is a streamable-HTTP MCP server. Any client that speaks MCP — Claude, Cursor, Windsurf, your own agent — connects with a URL and nothing else.
{
"mcpServers": {
"birthstar": { "url": "https://mcp.birthstar.ai/mcp" }
}
}The one rule worth knowing
Credits meter engine computation, never tool calls. create_chart costs one credit and returns a handle; every analytical read off that handle costs nothing. Design your agent to compute once and ask freely.
// 1. One metered call mints a handle. 1 credit.
const { chart_id } = await client.callTool({
name: "create_chart",
arguments: {
dob: "1990-03-14", tob: "09:20", tz: "Asia/Kolkata",
lat: 26.9124, lon: 75.7873
}
});
// 2. Every read off that handle is free. Ask as much as you like.
const grahas = await call("get_grahas", { chart_id });
const dasha = await call("get_current_dasha", { chart_id });
const yogas = await call("get_yogas", { chart_id });
const transits = await call("get_transits", { chart_id });
// 3. A successful call can still be a failed operation.
if (grahas.error) handle(grahas.type); // check the key, not the statusChart handles are self-describing
A handle is an encrypted token carrying the birth data it names, scoped to the account that minted it. Two consequences you can build on: a handle never expires out from under a running conversation — if the cache has evicted it, the server recomputes rather than failing — and any replica can serve any handle. You do not need sticky sessions.
Free to start, free with a key
Nothing costs money today and every tool is reachable either way. What you spend is credits, and only when a call actually runs the ephemeris. Without a key you share a public trial pool; with a free key you get a balance of your own. The trial numbers below are read live from the running server.
Could not reach the engine to read current limits: backend returned HTTP 503
Trial, no key
available nowA shared pool, open to everyone. No key, no account, no card. All 30 tools are reachable. Everyone without a key draws from the same balance, so it can run out for the day.
Free API key
available nowSign in with Google and get a key. Send it as the X-Birthstar-Key header and your calls are metered against your own balance instead of the shared pool.
Dedicated
not yet purchasableThere is no paid plan yet and no prices have been set. This is the shape being built — listed so you can tell us what you actually need before it is fixed.
How a credit is spent
create_chartandcalculate_birth_star— 1 credit each. Real ephemeris work.get_timeline— 1 credit. It recomputes a natal document to find turning points.rectify_birth_time— 1 credit per candidate chart tested, minimum 20 per call, charged up front. It works near a birth time you already have, scanning the minutes around it to find how many genuinely different charts the window holds. A wide scan is expensive by design; it is the tool that self-throttles.- Everything else reading an existing handle — 0 credits.
- A cache hit costs nothing, and a failed computation is refunded.
30 tools, one cost question
There is no premium tier and no tool is locked behind a plan — all 30 are reachable on the free pool. The only question that costs you anything: does the call run the ephemeris, or read a chart you already computed? 4 compute, and draw down the credits above. The other 26 read off a handle you already hold and cost nothing.
Computes a chart
4 tools1 credit eachReal astronomical work. Debits the credit ledger, and is refunded if it fails.
| Tool | What it returns |
|---|---|
| create_chart | Compute a full natal chart and return a handle. Call this first. |
| calculate_birth_star | One-shot nakshatra and core anchors, without a full chart. |
| get_timeline | Turning points between two dates. Recomputes a natal document to find them. |
| rectify_birth_time | Narrow a recorded birth time by scanning the minutes around it — how many genuinely different charts does your uncertainty window hold? The exception: 1 credit per candidate chart tested (min 20 per call), up to 241 — keep the window narrow. |
Reads a chart you already have
26 toolsfreeServed off the chart handle. No ephemeris work, no debit, no limit on how many you call.
| Tool | What it returns |
|---|---|
| get_grahas | Planetary positions, dignity and state. |
| get_houses | The twelve bhavas. |
| get_panchanga | Tithi, vara, nakshatra, yoga and karana at birth. |
| get_day_periods | Sunrise/sunset, Rahu kala and the day windows. |
| get_current_dasha | The dasha periods running right now. |
| get_dasha_periods | Walk the dasha tree at any level, past or future. |
| get_transits | Gochara — planets now against the natal chart. |
| get_yogas | Classical combinations whose conditions actually hold. |
| get_strengths | Shadbala, Bhava Bala, Ishta/Kashta phala. |
| get_ashtakavarga | Bindu point-scores per sign, for transit strength. |
| get_vimsopaka | Dignity-weighted strength across the 16 vargas. |
| get_aspects | Graha and rashi drishti — who looks at which house. |
| get_varga | One divisional chart from a cached chart. |
| get_lagna_points | Special lagnas, Arudha padas, Bhrigu Bindu. |
| get_karakas | Chara karakas plus Karakamsa and Swamsa. |
| get_avasthas | Maturity, alertness and mood states per graha. |
| get_fixed_stars | Real conjunctions with named prominent fixed stars. |
| get_longevity | Ayurdaya estimates. Experimental, not for predictive use. |
| get_compatibility | 36-point Ashta-Kuta Guna Milan between two charts. |
| get_doshas | Kuja, Kaal Sarp, Gandanta and Pitre audits. |
| get_numerology | Chaldean name and Vedic date-of-birth numbers. |
| describe_chart | Metadata and inventory of what a cached chart holds. |
| get_prompt_library | Curated prompt templates and multi-tool workflows. |
| get_account_status | Your plan, remaining credits and reset date. |
| health_check | Configuration and accuracy self-test. |
| server_stats | Calls, latency, errors and payload sizes for this session. |
Apps you can build by pasting a prompt
Each of these is a complete build prompt — the endpoint, the exact tool chain, the credit model and the honesty constraints, already written. Paste one into Claude Code, Cursor or v0 and you get a working app, not a scaffold to finish yourself.
Every prompt names real tools with real arguments, checked against the server. Pair one with the Claude Skill and your agent already knows the calling convention before it writes a line.
Twelve prompts and a Claude Skill, already written
The good tool chains are already worked out. Twelve workflows ship as native MCP prompts your client lists directly — no tool round-trip.
Native MCP prompts
Claude Skill
freeDrop one file in .claude/skills/ and your agent stops guessing at astronomy.
- The credit model, so it does not burn charts
- Tool selection per question type
- Error recovery that stops instead of retrying
- Sidereal vs tropical, and never faking a null
Errors are returned, not raised
A tool that raises gives your model a stack trace. Every Birthstar tool returns a JSON object with an error string and a type your code can branch on — which means a successful MCP call can still be a failed operation. Check for the error key, not the transport status.
UnknownChartThe string is not a chart handle at all.
Call create_chart.
StaleHandleA handle issued under an older key version.
Call create_chart again.
ForbiddenChartA valid handle owned by a different account.
Recreate under this account.
SubscriptionRequiredTool or argument is outside the plan.
Check get_account_status first.
InsufficientCreditsOn-plan, but the balance cannot cover it.
Carries credits_needed and credits_reset_at.
RateLimitedPast the per-minute compute ceiling.
Carries retry_after_s. Back off.
InputTooLargeA list or string argument past its cap.
Message names the argument and limit.
TimeErrorBad date, time or timezone.
Message states the expected format.
ConfigErrorUnknown ayanamsha, house system or node type.
Message names the bad value.
CalcErrorEngine computation failure.
Message carries the engine reason.
VargaNotAvailableVarga outside the computed set.
Response lists computed and not_computed.
InternalErrorA bug in the server.
Carries error_id. Quote it in a report.
Not in the box yet
Things you will look for and not find. Better stated here than discovered halfway through a build. Each one is a real gap, not a teaser — none of them has a ship date.
One key per account, and no usage dashboard yet
Signing in with Google gives you one API key with its own monthly balance. You can replace it, but not hold several, name them, or see per-key usage. claude.ai custom connectors cannot send the key header, so they use the shared trial.
Several named keys, per-key usage, and keys that work from claude.ai connectors.
No plain REST API
The engine speaks MCP. There is a JSON dashboard endpoint for calculating a chart, but no documented, versioned, stable REST surface you should build a product against.
A versioned HTTP API with the same tool semantics, for callers that are not agents.
The credit ledger is single-process
Chart handles are horizontally safe — they carry their own birth data, so any replica can serve them. The ledger is not: it is a local file, so a multi-replica deployment does not share one balance.
A shared ledger backend so quota is exact under horizontal scale.
No MCP resources
Prompts do ship: twelve curated workflows are registered as native MCP prompts, so your client lists them without a tool round-trip. Resources are the half that is missing — there is no addressable chart or reference document a client can subscribe to and read directly.
A computed chart exposed as a resource, so clients can attach it as context instead of re-querying tools.
No webhooks or subscriptions
Every answer is pull-only. Nothing can notify you when a dasha changes or a transit becomes exact — you have to ask on a schedule you run yourself.
Subscribe to a chart and receive turning points as they arrive.
No batch endpoint
One chart per create_chart call. Computing a cohort means N round-trips and N credits, with per-call latency you cannot amortise.
A batch compute that takes many births and returns many handles.
No official SDK package
You connect with a standard MCP client. There is no typed, published npm or PyPI wrapper with argument types and return shapes for these thirty tools.
Generated, typed clients so tool arguments are checked at compile time.
What the engine reports right now
Read from /usage at page load. Your own client can read the same thing at any time by calling get_account_status or server_stats.
backend returned HTTP 503