Utilizes OpenStreetMap's Nominatim geocoding service to resolve birth places into latitude, longitude, timezone, and timezone-aware datetimes for astrological calculations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@stellara-mcp Calculate my natal chart for March 14, 1990 at 9:30 AM in Austin, Texas."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your AI agent a real astronomical calculator. stellara-mcp is a tiny,
open-source Model Context Protocol server that
turns any MCP-capable agent — Claude.ai / Claude Desktop / Claude Code, ChatGPT, Codex,
Cursor, Windsurf, Gemini CLI, Grok, Hermes — into an astrologer that never invents a
planetary position. Connect by URL (no install) or run the package locally with an API key.
It exposes four tools backed by Swiss Ephemeris (the same engine professional astrologers use) running in the Stellara cloud:
Tool | What you get back (exact JSON) |
| "Warsaw, 14:30" → latitude / longitude, IANA timezone and a tz-aware |
| 14 points (Sun → Pluto, Chiron, Lilith, North/South Node) with sign, degree, absolute longitude, house, retrograde, speed, declination · 12 house cusps · Ascendant / MC / Descendant / IC · every major aspect with its exact orb and applying / separating |
| Transiting positions at any moment · every transit-to-natal aspect (planets and angles) with orb and applying / separating · which natal house each transiting planet occupies |
| All inter-chart aspects between two people with exact orbs · house overlays (A's planets in B's houses and vice versa) |
Plus two MCP prompts: collect_birth_profile, a guided intake of the data every
reading depends on (date → time with certainty → place → optional city, name,
gender → confirmation card with age), and astrologer_system_prompt, which
switches the agent into a disciplined professional-astrologer style for
interpreting that JSON.
The server does not interpret and does not call any LLM. It is a proxy adapter: numbers in, numbers out. Your agent does the reading; Swiss Ephemeris does the math.
Ask a language model "where was my Moon on 17 May 1990 at 14:30 in Warsaw?" and it will answer confidently — and, more often than not, wrongly. Ecliptic longitudes, house cusps and aspect orbs are the output of numerical integration of planetary motion plus spherical trigonometry for the local horizon. That is not something a next-token predictor can do in its head. Typical failure modes:
the Moon (13° per day) lands in the wrong sign;
the Ascendant is guessed from the Sun sign, ignoring time and latitude;
house cusps are fabricated or silently assume Equal houses;
"Saturn square Sun" is asserted with no orb, or with an orb that does not exist;
retrograde status is invented.
Every one of those errors poisons the whole interpretation that follows. A reading built on a wrong Ascendant is worthless no matter how eloquent it is.
stellara-mcp fixes this at the root. The agent calls a tool; the tool returns
Swiss-Ephemeris-grade positions (sub-arcsecond precision, tropical zodiac, ten house
systems, exact orbs, applying/separating derived from real planetary speeds); the
agent interprets only that data. Deterministic senses, deterministic
calculator — the language model is left to do what it is actually good at.
Related MCP server: Astro MCP Server
Two ways to connect:
Remote, no install (Claude.ai, Claude Desktop, Claude Code, ChatGPT connectors,
Grok, any client that takes an MCP URL): add a custom connector with the URL
https://mcp.stellara.natlex.it/mcp and sign in with your Stellara account
(the same account as the Stellara app; Free = 10 requests / day, Stellara Pro = 5 000).
Claude: Settings → Connectors → Add custom connector → paste the URL → Connect → sign in.
Claude Code: claude mcp add --transport http stellara https://mcp.stellara.natlex.it/mcp,
then /mcp to sign in. Nothing to install, nothing to configure; tokens are short-lived
and can be revoked from the app.
Local package + API key (below): for servers, scripts, Cursor / Windsurf / Codex and anyone who prefers a key. Get one at stellara.natlex.it/#api — Free (5 requests / day) or Stellara API Pro (5 000 / day, $9 / month), delivered by e-mail within a minute. Then pick your client.
The package runs on Node.js ≥ 18.17 and is launched with
npx, so nothing to install globally. All configs below are the same three lines: command, args, env.
Edit claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"stellara": {
"command": "npx",
"args": ["-y", "stellara-mcp"],
"env": {
"STELLARA_API_KEY": "sk_stellara_your_key_here"
}
}
}
}Restart Claude Desktop. The three tools appear under the 🔌 icon; the
astrologer_system_prompt prompt appears in the prompts (+) menu.
Add the same block to ~/.hermes/config.json:
{
"mcpServers": {
"stellara": {
"command": "npx",
"args": ["-y", "stellara-mcp"],
"env": {
"STELLARA_API_KEY": "sk_stellara_your_key_here"
}
}
}
}Hermes discovers the tools on next launch. If your Hermes build uses a different
top-level key for MCP servers, keep the command / args / env triple as is —
it is the standard stdio launch spec.
Cursor: Settings → MCP → Add new global MCP server (or .cursor/mcp.json in a
project). Windsurf: Settings → Cascade → MCP servers (or
~/.codeium/windsurf/mcp_config.json). Both take the identical JSON:
{
"mcpServers": {
"stellara": {
"command": "npx",
"args": ["-y", "stellara-mcp"],
"env": {
"STELLARA_API_KEY": "sk_stellara_your_key_here"
}
}
}
}Launch npx -y stellara-mcp as a stdio server with the environment variable
STELLARA_API_KEY set. That is the whole integration surface.
git clone https://github.com/mihnin/stellara-mcp.git
cd stellara-mcp
npm install && npm run buildthen use "command": "node", "args": ["/absolute/path/to/stellara-mcp/dist/index.js"]
in any of the configs above.
User: Build my natal chart — I was born on 17 May 1990 at 14:30 in Warsaw — and tell me why work feels so heavy today.
Agent (loads
astrologer_system_prompt, asks whether 14:30 is exact or approximate, callsresolve_birth_place("Warsaw, Poland", "1990-05-17T14:30")→ 52.23 / 21.01, Europe/Warsaw,1990-05-17T14:30:00+02:00, thencalculate_natal_chartwith those values, thenget_transits_and_aspectsfor today)Your chart is built from Swiss Ephemeris positions, so let's start with what's actually there. Sun at 26°14' Taurus in the 9th house, Moon at 3°52' Capricorn in the 4th, Ascendant 8°41' Virgo. The tightest natal aspect is Saturn conjunct Neptune (orb 0.6°) sitting in your 5th house — a lifelong tension between structure and drift in creative work.
Why today is heavy: transiting Saturn is squaring your natal Sun with an orb of 1.2° and it is applying, so the pressure is still building toward exact in about two weeks. Saturn squares to the Sun feel like carrying a backpack of obligations — output is fine, but everything costs more effort. At the same time transiting Mars is passing through your natal 6th house of daily work (Aquarius), conjunct your natal Mercury with a 0.4° orb: fast, irritable, prone to arguing with tools and colleagues.
Practical read: this is a "finish, don't start" window. Close the two tasks with deadlines, defer the brainstorming to after the Saturn square separates, and don't read the Mars–Mercury irritability as a sign that the job is wrong. If you can, I'd like your birth time to the minute — the Ascendant at 8° Virgo is close to a sign boundary, and the house placements above depend on it.
Every degree, orb and "applying" in that answer came from a tool result; the interpretation is the agent's. That separation is the entire point.
Chart tools take datetimes as ISO-8601 with a timezone (1990-05-17T14:30:00+02:00
or ...Z); naive values are rejected before any network call. Coordinates are
decimal degrees (north / east positive). The intended flow is resolve_birth_place
first — it produces exactly those values from what the user actually says.
resolve_birth_placeInput | Type | Notes |
| string | Free text, any language: |
| string (optional) | Local wall-clock time without an offset: |
Output:
{
"query": "Warsaw", "display_name": "Warszawa, województwo mazowieckie, Polska",
"latitude": 52.2333742, "longitude": 21.0711489, "timezone": "Europe/Warsaw",
"local_datetime": "1990-05-17T14:30:00", "utc_offset": "+02:00",
"birth_datetime": "1990-05-17T14:30:00+02:00", "birth_datetime_utc": "1990-05-17T12:30:00Z",
"time_assumed_noon": false, "local_time_ambiguity": "none", "age_years": 36,
"source": "nominatim"
}birth_datetime, latitude and longitude go straight into the chart tools.
local_time_ambiguity is ambiguous_dst_fallback when the wall time happened
twice (autumn clock change) and nonexistent_dst_gap when the clocks skipped it —
the agent should ask which one the user means. Offsets come from the IANA tz
database, so 1985 Moscow resolves to +04:00 and 2015 Moscow to +03:00. Errors:
PLACE_NOT_FOUND (try a larger nearby city / add the country) and
GEOCODER_UNAVAILABLE (transient — retry). Geocoding uses OpenStreetMap
Nominatim; nothing about the request is stored.
calculate_natal_chartInput | Type | Notes |
| string | ISO-8601 with tz |
| number | −90 … 90 |
| number | −180 … 180 |
| enum |
|
| boolean | default |
Output (abridged):
{
"input": { "birth_datetime_utc": "1879-03-14T10:30:00Z", "latitude": 48.4011, "longitude": 9.9876, "house_system": "placidus" },
"planets": [
{ "name": "Sun", "sign": "Pisces", "degree": 23.498749, "absolute_longitude": 353.498749,
"house": 10, "retrograde": false, "speed": 0.995959, "declination": -2.585261 }
],
"houses": [ { "house": 1, "sign": "Cancer", "degree": 7.4423, "absolute_longitude": 97.4423 } ],
"angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...} },
"aspects": [
{ "point_a": "Sun", "point_b": "Mercury", "aspect": "conjunction", "exact_degrees": 0, "orb": 9.627514, "movement": "separating" }
],
"meta": { "engine": "Swiss Ephemeris (kerykeion 5.12.7)", "zodiac": "tropical", "house_system": "placidus", "orbs": {...}, "time_resolution": "minute" }
}get_transits_and_aspectsInput | Type |
| object — same fields as |
| string — ISO-8601 with tz |
| boolean |
Returns natal (the full chart above), target_datetime_utc, transiting_planets
(same point shape plus natal_house), and aspects_to_natal:
{ "transiting": "Saturn", "natal": "Sun", "aspect": "square", "exact_degrees": 90, "orb": 1.21, "movement": "applying" }movement is computed with the natal point held fixed — only the transiting body
moves — using the real planetary speed for that instant.
calculate_synastryInput | Type |
| object — same fields as |
| boolean |
Returns both full charts, inter_aspects (point_a belongs to A, point_b to B,
with orb), and house_overlays (a_in_b_houses, b_in_a_houses).
collect_birth_profileArgument (optional): language. A fixed-order intake the agent walks through
before any chart: 1 date of birth → 2 time of birth with its certainty
(exact / approximate / unknown → 12:00 and no house interpretation) → 3 place
of birth, resolved through resolve_birth_place and confirmed with the user →
4 current city (optional, only to interpret "today" in local time) → 5
name (optional) → 6 gender (optional, asked only for synastry) → 7 a
confirmation card with the resolved coordinates, timezone, birth_datetime and
age. Mirrors the profile the Stellara app collects, minus anything the
calculation does not need.
astrologer_system_promptArguments (both optional): language — the language to answer in; focus — the
user's current concern. The prompt carries the same intake rules, mandates
resolve_birth_place for coordinates and offsets, and instructs the agent to use
tool JSON as the only source of positions, cite orbs, respect applying/separating,
flag unreliable houses when the birth time is unknown, and keep interpretation
separate from calculation.
Variable | Required | Default | Purpose |
| yes | — | Access key, sent as |
| no |
| Point at a self-hosted Stellara backend (the raw Cloud Run URL |
| no |
| Per-request timeout |
Errors are returned as MCP tool errors with an actionable message — invalid or
revoked key (401), place not found (404), rate limit (429, 60 requests / minute /
IP; 20 for resolve_birth_place), daily quota used up (429 with
QUOTA_EXCEEDED — the message tells the agent when the quota resets at 00:00 UTC
and where to upgrade the key), backend validation detail (422), geocoder or
backend outage (5xx), network failure, timeout. The server never
crashes at launch because of configuration; it explains the problem when a tool is
called, which is what desktop agents handle best.
Keys come in tiers: free (5 requests / day — enough to try every tool) and Stellara API Pro (5 000 / day, $9 / month) — see stellara.natlex.it/#api.
The same package also runs as an HTTP service — node dist/remote.js — which is what
https://mcp.stellara.natlex.it/mcp is (Cloud Run, stateless, one McpServer per
request). It is an OAuth 2.1 resource server: GET /.well-known/oauth-protected-resource/mcp
points clients at the authorization server (the Stellara backend, https://api.stellara.natlex.it,
DCR + CIMD + PKCE S256), an unauthenticated POST /mcp answers 401 with
WWW-Authenticate: Bearer … resource_metadata="…", and a valid token — an OAuth access
token or an sk_stellara_ key sent as Authorization: Bearer — is forwarded to the API,
which enforces the daily quota. GET /health for monitoring; GET /mcp is 405 (no SSE
stream, no sessions).
Variable | Required | Default | Purpose |
| yes | — | HS256 secret shared with the authorization server (the service refuses to start without it) |
| no |
| Public origin; |
| no |
| Authorization server (RFC 8414 issuer) |
| no |
| Listen port (Cloud Run sets it) |
| no | — | When set, |
| no | as above | Same as stdio mode |
The calculator behind the tools is the Stellara API (FastAPI + kerykeion / pyswisseph),
hosted at https://api.stellara.natlex.it. The MCP server itself is a thin, stateless
adapter: point STELLARA_API_BASE_URL at another instance of the API and everything
else stays the same. The backend is not published as open source; for a private
deployment write to info@natlex.it.
docs/USAGE.ru.md — инструкция для пользователей (на русском): установка в Claude Desktop / Cursor / Hermes, получение ключа, примеры диалогов, что делать при ошибках.
Maintainer runbook (npm release, official MCP Registry, catalogues, remote-service deploy) lives in the private Stellara monorepo (docs/PUBLISHING.md there) and is not published.
This repository is the public source of the npm package and the remote service. Day-to-day
development happens in the private Stellara monorepo; every release is synced here as a
single commit (sync: stellara-mcp <version>). Issues are welcome here; pull requests are
merged into the monorepo and land here with the next sync.
npm install
npm test # vitest: every behavioural test drives the real MCP protocol
npm run build # tsc → dist/
npm start # runs the stdio serverTests connect an MCP Client to the server over an in-memory transport, stub
fetch, and assert exactly what a desktop agent would observe: tool discovery,
schema rejection before any network call, request shape (URL, headers, body), the
JSON passthrough, every error mapping, timeouts and the prompt text.
MIT © Natlex. Swiss Ephemeris is © Astrodienst AG and is used on the server side under its license via kerykeion.
Use this tool for ANY natal chart / birth chart or personal horoscope request — never compute or recall planetary positions, houses or aspects yourself and never web-search them; call resolve_birth_place first when you only have a place name and a local time. Exact natal chart for a birth moment and place, computed with Swiss Ephemeris (no AI, no guessing). Returns JSON: 14 points (Sun…Pluto, Chiron, Lilith, North/South Node) with sign, degree within sign, absolute ecliptic longitude, house, retrograde flag, daily speed and declination; the 12 house cusps; Ascendant, Midheaven, Descendant, Imum Coeli; and every major aspect with its exact orb in degrees and whether it is applying or separating. Tropical zodiac. Use the result as the only source of positions when interpreting.
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | Yes | Birth latitude in decimal degrees (north positive) | |
| longitude | Yes | Birth longitude in decimal degrees (east positive) | |
| house_system | No | House system; default 'placidus'. One of: placidus, koch, porphyry, regiomontanus, campanus, equal, whole_sign, topocentric, morinus, alcabitius | placidus |
| birth_datetime | Yes | ISO-8601 date-time WITH timezone, e.g. '1990-05-17T14:30:00Z' or '1990-05-17T17:30:00+03:00'. Convert the local birth time to an offset yourself; naive values are rejected. | |
| include_minor_aspects | No | Also report minor aspects (semi-sextile, semi-square, quintile, sesquiquadrate, biquintile, quincunx) with tight orbs. Default false = the five major aspects only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, idempotent, and openWorld hints, and the description adds substantial non-obvious behavior: it uses Swiss Ephemeris rather than AI or guessing, returns an exact tropical chart, and enumerates the full result shape including aspects, orbs, applying/separating flags, house cusps and angles. Nothing in the description contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the usage condition and prerequisite before the output details. It is dense and somewhat run-on in the first sentence, but every clause carries information about behavior or return shape, so it earns a high score rather than a maximum.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex calculation tool with no output schema, and the description compensates fully by specifying the 14 points, house cusps, angles, aspect types, orbs, applying/separating status and zodiac. Combined with the fully described input schema, an agent has everything needed to invoke and interpret the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter already has a thorough description, so the baseline is 3. The description adds useful context by explaining that the birth place and local time must be resolved through resolve_birth_place before supplying latitude, longitude and birth_datetime, and by tying the result fields to the input birth moment and place.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact resource (natal chart / birth chart / personal horoscope) and a specific action (compute with Swiss Ephemeris). It also distinguishes itself by explicitly forbidding self-computation or web-search and pointing to resolve_birth_place for place-name-only inputs, so an agent can tell it apart from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use the tool: for ANY natal chart or personal horoscope request. It gives an explicit when-not by saying never compute or recall positions yourself and never web-search them, and it names the alternative resolve_birth_place as a prerequisite when only a place name and local time are available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this tool for ANY compatibility / relationship / synastry question about two people — never estimate inter-chart aspects yourself and never web-search them. Relationship astrology for two birth charts: every inter-chart aspect (person A's points × person B's points, planets and angles) with exact orbs, plus house overlays (A's planets in B's houses and vice versa). Both full natal charts are embedded in the response.
| Name | Required | Description | Default |
|---|---|---|---|
| person_a | Yes | First person's birth data | |
| person_b | Yes | Second person's birth data | |
| include_minor_aspects | No | Also report minor aspects (semi-sextile, semi-square, quintile, sesquiquadrate, biquintile, quincunx) with tight orbs. Default false = the five major aspects only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavior beyond that: it reports every inter-chart aspect at exact orbs, includes house overlays, and embeds both full natal charts in the response. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with the primary trigger and prohibition front-loaded, followed by a compact but complete specification of the output. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining return value, and it does: every inter-chart aspect with orbs, house overlays both directions, and embedded natal charts. The input schema covers all parameters, so an agent has everything needed to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed descriptions for birth_datetime, coordinates, house_system, and include_minor_aspects. The prose adds no parameter-specific semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact resource ('compatibility / relationship / synastry question about two people') and enumerates the computed output: every inter-chart aspect with exact orbs plus house overlays. This differentiates it from single-chart tools like calculate_natal_chart or time-based get_transits_and_aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use the tool for ANY two-person compatibility/synastry question and forbids estimating aspects or web-searching them. It does not name sibling tools or state when not to use this tool (e.g., single chart → calculate_natal_chart), so it stops short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this tool for ANY 'what is going on for me now / today / this week / this month', daily-weekly-monthly-yearly horoscope, forecast or transit question — never estimate transiting positions yourself and never web-search them. Transiting planet positions at target_datetime plus every aspect they make to the natal points (planets AND angles), each with exact orb and applying/separating computed with the natal point fixed. Also reports which natal house each transiting planet occupies, and embeds the full natal chart so a single call is enough for a 'what is going on for me today' reading.
| Name | Required | Description | Default |
|---|---|---|---|
| natal | Yes | The person's birth data | |
| target_datetime | Yes | Moment to compute transits for, ISO-8601 WITH timezone (e.g. now, or a date the user asks about) | |
| include_minor_aspects | No | Also report minor aspects (semi-sextile, semi-square, quintile, sesquiquadrate, biquintile, quincunx) with tight orbs. Default false = the five major aspects only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, the description discloses detailed behavior: it computes transiting planet positions at target_datetime, all aspects to natal points including angles, exact orbs, applying/separating states, natal house placement per transiting planet, and embeds the full natal chart. This gives the agent a clear model of what the tool does internally without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the usage directive and followed by a compact feature list. Every clause earns its place—no filler, no repetition of schema details, and the most important guidance comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a fairly complex astrological computation with no output schema, the description covers what is computed, which points are included, and what extra data is embedded (houses, full chart). It does not describe the exact response structure or pagination/format details, but for the agent's invocation decision the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond field names by explaining how target_datetime is used ('transiting planet positions at target_datetime') and how natal relates to it ('every aspect ... to the natal points ... with the natal point fixed'). This helps an agent understand which parameter drives which behavior, though the schema already documents the basics well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('compute transits to a natal chart') and immediately ties it to concrete user intents: 'what is going on for me now / today / this week / this month', horoscopes, forecasts, and transit questions. This clearly distinguishes it from siblings like calculate_natal_chart (static chart) and calculate_synastry (relationship chart).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this tool for ANY ... forecast or transit question' and instructs the agent to 'never estimate transiting positions yourself and never web-search them', giving strong when-to-use guidance. It does not explicitly name alternative sibling tools or state when NOT to use them, stopping just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this FIRST whenever a birth date / time and a place of birth appear in the conversation — for a natal chart, a horoscope, transits or synastry, even if the user does not mention Stellara. Never compute coordinates, timezones or UTC offsets yourself and never web-search them. Geocodes the place (any language, e.g. 'Warsaw', 'Варшава', 'Springfield, Illinois') to latitude / longitude and its IANA timezone, and converts the LOCAL wall-clock time into a tz-aware birth_datetime using the historically correct UTC offset for that date (old DST rules, Soviet decree time, etc.). Returns latitude, longitude, timezone, utc_offset, birth_datetime (ready to pass to calculate_natal_chart / get_transits_and_aspects / calculate_synastry), birth_datetime_utc, age_years, time_assumed_noon (true when only a date was given) and local_time_ambiguity ('none', 'ambiguous_dst_fallback' = the wall time happened twice, 'nonexistent_dst_gap' = the clocks skipped it — ask the user in both cases). Nothing is stored server-side.
| Name | Required | Description | Default |
|---|---|---|---|
| place | Yes | Place of birth as free text, in any language; add region/country for small towns | |
| local_datetime | No | Birth time as the user said it, in LOCAL time WITHOUT an offset: 'YYYY-MM-DDTHH:MM[:SS]'. Pass 'YYYY-MM-DD' alone if the time is unknown (12:00 is assumed and flagged). Never add +HH:MM or Z here — the server derives the historical offset from the place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it explains DST ambiguity handling, the 'time_assumed_noon' flag, the 'local_time_ambiguity' field, and that nothing is stored server-side. It doesn't fully explain what happens in ambiguous/nonexistent cases beyond 'ask the user', but the disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized, front-loading the most important usage instruction ('Call this FIRST'). It packs a lot of information into a few sentences, though the list of return fields is long and could be slightly more scannable. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, 100% schema coverage, and no output schema, the description is remarkably complete. It explains the return fields, the ambiguity flags, the noon assumption, the historical timezone handling, and the privacy behavior. An agent has everything it needs to call this tool correctly and interpret its output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description adds meaning by explaining that local_datetime must be in LOCAL time without an offset, and that 'YYYY-MM-DD' alone triggers noon assumption. It also clarifies that the place can be in any language. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('resolve') and resource ('birth place'), and clearly distinguishes this tool from siblings by naming the downstream tools it feeds. It also explicitly says to call it FIRST whenever birth data appears, which differentiates it from calculate_natal_chart, get_transits_and_aspects, and calculate_synastry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Call this FIRST whenever a birth date / time and a place of birth appear in the conversation'), and explicit when-not-to-use guidance ('Never compute coordinates, timezones or UTC offsets yourself and never web-search them'). It also names the downstream tools that consume its output, making the workflow clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.2calculate_natal_chartcalculate_synastryget_transits_and_aspectsresolve_birth_placeScored across 4 tools
Each tool targets a distinct astrological workflow: birth-place resolution, natal chart calculation, synastry, and transits. Even though natal charts are embedded in synastry and transit responses, the purpose of each tool is clearly separated by the type of request it handles.
All tool names follow a clean verb_noun snake_case pattern: resolve_birth_place, calculate_natal_chart, calculate_synastry, get_transits_and_aspects. The verbs correspond naturally to each operation, making the naming predictable and consistent.
Four tools is a tight, well-scoped set for an astrology calculation server. Each tool addresses a distinct core request type with no redundancy or filler tools.
The core astrological workflows are covered end-to-end: resolving birth data, calculating a natal chart, analyzing synastry, and computing transits. Advanced techniques such as composite charts, progressions, or solar returns are not present, but these are reasonable omissions for a focused tool set.
Western natal charts, horoscopes, transits and synastry for AI agents, verified vs NASA JPL.
Real astrology for AI agents: cosmic weather, synastry, timing, astrocartography, and divination.
Vedic and Western astrology for AI agents: charts, dasha, matchmaking, panchanga, numerology, tarot.
Astrology transit forecasts, timelines and significant-date feeds for AI agents.
