Skip to main content
Glama

Stellara MCP: Deterministic Swiss Ephemeris for AI Agents (Hermes, Claude, Grok)

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)

resolve_birth_place

"Warsaw, 14:30" → latitude / longitude, IANA timezone and a tz-aware birth_datetime with the historically correct UTC offset (old DST rules, decree time), plus age and DST-ambiguity flags — so the agent never guesses coordinates or offsets

calculate_natal_chart

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

get_transits_and_aspects

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

calculate_synastry

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.


Why this exists: LLMs lie about natal charts

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

Quick start (1-click configs)

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.

Claude Desktop

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.

Hermes Agent Desktop

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 / Windsurf

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"
      }
    }
  }
}

Any other MCP client (Grok bridges, Continue, Zed, custom agents)

Launch npx -y stellara-mcp as a stdio server with the environment variable STELLARA_API_KEY set. That is the whole integration surface.

From a local clone (for development)

git clone https://github.com/mihnin/stellara-mcp.git
cd stellara-mcp
npm install && npm run build

then use "command": "node", "args": ["/absolute/path/to/stellara-mcp/dist/index.js"] in any of the configs above.


Example conversation

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, calls resolve_birth_place("Warsaw, Poland", "1990-05-17T14:30") → 52.23 / 21.01, Europe/Warsaw, 1990-05-17T14:30:00+02:00, then calculate_natal_chart with those values, then get_transits_and_aspects for 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.


Tool reference

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_place

Input

Type

Notes

place

string

Free text, any language: Warsaw, Варшава, Springfield, Illinois, USA

local_datetime

string (optional)

Local wall-clock time without an offset: 1990-05-17T14:30, or 1990-05-17 if the time is unknown (12:00 assumed and flagged)

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_chart

Input

Type

Notes

birth_datetime

string

ISO-8601 with tz

latitude

number

−90 … 90

longitude

number

−180 … 180

house_system

enum

placidus (default), koch, porphyry, regiomontanus, campanus, equal, whole_sign, topocentric, morinus, alcabitius

include_minor_aspects

boolean

default false — majors only (conjunction 10°, opposition 10°, trine 8°, square 8°, sextile 6°)

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_aspects

Input

Type

natal

object — same fields as calculate_natal_chart

target_datetime

string — ISO-8601 with tz

include_minor_aspects

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_synastry

Input

Type

person_a, person_b

object — same fields as calculate_natal_chart

include_minor_aspects

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).

Prompt: collect_birth_profile

Argument (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.

Prompt: astrologer_system_prompt

Arguments (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.


Configuration

Variable

Required

Default

Purpose

STELLARA_API_KEY

yes

—

Access key, sent as X-API-Key. Request one at stellara.natlex.it/#api. Without it every tool returns a clear error that says where to get one.

STELLARA_API_BASE_URL

no

https://api.stellara.natlex.it/api/v1/astrology

Point at a self-hosted Stellara backend (the raw Cloud Run URL https://stellara-api-923668916124.us-central1.run.app/api/v1/astrology also works)

STELLARA_TIMEOUT_MS

no

15000

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.


Remote mode (Streamable HTTP)

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

JWT_SECRET

yes

—

HS256 secret shared with the authorization server (the service refuses to start without it)

MCP_PUBLIC_URL

no

https://mcp.stellara.natlex.it

Public origin; <origin>/mcp is the token audience (RFC 8707 resource)

OAUTH_ISSUER

no

https://api.stellara.natlex.it

Authorization server (RFC 8414 issuer)

PORT

no

8080

Listen port (Cloud Run sets it)

GLAMA_CLAIM_TOKEN

no

—

When set, GET /.well-known/glama.json publishes the Glama connector ownership claim (public by design)

STELLARA_API_BASE_URL, STELLARA_TIMEOUT_MS

no

as above

Same as stdio mode


Self-hosting the calculator

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.


Guides

  • 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.

Source

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.

Development

npm install
npm test          # vitest: every behavioural test drives the real MCP protocol
npm run build     # tsc → dist/
npm start         # runs the stdio server

Tests 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.

License

MIT © Natlex. Swiss Ephemeris is © Astrodienst AG and is used on the server side under its license via kerykeion.

Available Tools

4 tools
calculate_natal_chartCalculate natal chart (Swiss Ephemeris)A
Read-onlyIdempotent
Inspect

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.

Inputs: latitude (required), longitude (required), birth_datetime (required), house_system, +1 more.

calculate_synastrySynastry between two peopleA
Read-onlyIdempotent
Inspect

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.

Inputs: person_a (required), person_b (required), include_minor_aspects.

get_transits_and_aspectsTransits to a natal chartA
Read-onlyIdempotent
Inspect

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.

Inputs: natal (required), target_datetime (required), include_minor_aspects.

resolve_birth_placeResolve birth place → coordinates, timezone, exact birth instantA
Read-onlyIdempotent
Inspect

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.

Inputs: place (required), local_datetime.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Multi-tradition astrology engine that computes real birth charts, transits, and synastry for AI agents via MCP tools.
      18
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      High-precision astrology tools for LLM agents, including natal charts, transits, progressions, synastry, and more, backed by Swiss Ephemeris.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to retrieve precise astrology calculations, including natal charts, transits, composites, harmonic midpoints, and ranked daily aspects, using real ephemeris data rather than guesses.
      5
      1
      AGPL 3.0