Auseklis Astrology

Official

by igmizo · TypeScript

Astrology from a real ephemeris: natal charts, transits, synastry, eclipses, returns. No API keys.

Generate astrological charts including natal charts, transits, synastry, and planetary returns.

Topics

astrologyclaudecloudflare-workersephemerismcpmcp-servernatal-charttypescript

README.md6 KBView on GitHub

auseklis

Astrology MCP server — natal charts, transits, synastry, progressions, returns, eclipses, retrogrades, moon phases. Computed from a real ephemeris, so AI agents stop hallucinating planet positions.

Named after the Latvian morning star. MIT-licensed with no AGPL ephemeris data — see Licensing.

Tools

Tool	What it does
`get_planet_position`	Position of one body/point at a moment (sign, degree, speed, retrograde)
`compute_natal_chart`	Full birth chart: 13 points, houses, angles, aspects
`compute_transits`	Aspects from the current (or any) sky to a natal chart
`compute_progressions`	Secondary progressions (day-for-a-year)
`compute_synastry`	Cross-chart aspects between two people
`compute_composite_chart`	Midpoint composite chart of a relationship
`find_returns`	Solar/lunar/planetary returns (exact moments)
`get_moon_phase`	Phase, illumination, Moon sign, next four quarters
`find_eclipses`	Lunar/solar eclipses with signs, incl. local visibility
`find_retrograde_periods`	Station retrograde/direct moments for any planet
`find_sign_ingresses`	When a body changes signs (equinoxes, Saturn ingresses, …)
`find_aspect_times`	Exact moment a transit perfects ("when does Saturn square my Sun?")

Plus two prompts (natal_chart_reading, current_sky_report) and a glossary resource (auseklis://glossary).

Features: local birth times with IANA timezones (full historical DST handling) · tropical and sidereal (Lahiri, Fagan/Bradley) zodiacs · whole-sign, equal, Porphyry, and Placidus houses · mean lunar nodes and Black Moon Lilith.

Installation

Claude Code

bash

claude mcp add auseklis -- npx -y auseklis

Claude Desktop / any MCP client (stdio)

json

{
  "mcpServers": {
    "auseklis": {
      "command": "npx",
      "args": ["-y", "auseklis"]
    }
  }
}

No API keys, no configuration — the ephemeris is computed locally.

Desktop Extension

Download auseklis.mcpb from the releases page and double-click to install in Claude Desktop. Or build it yourself: npm run bundle.

Remote (self-hosted)

The same server runs as a Cloudflare Worker speaking Streamable HTTP. Deploy it to your own account:

bash

npm run deploy   # wrangler deploy
claude mcp add --transport http auseklis https://auseklis.<your-subdomain>.workers.dev/mcp

Set the MCP_SHARED_SECRET secret to require a bearer token.

Example questions to ask

"Compute my natal chart — born 15 March 1990, 15:45 in Riga."
"What's transiting my Sun this month?"
"When exactly is my Saturn return?"
"Synastry between me and my partner?" (two birth date/times)
"When is Mercury retrograde in 2027, and in which signs?"
"Is tonight's full moon visible as an eclipse from here?"

The model handles place-name → coordinates; the server handles local-time → UTC via the IANA timezone database.

Accuracy

Positions come from astronomy-engine (VSOP87 + NOVAS C 3.1): ±1 arcminute for 1700–2200, far below the 1° resolution astrological interpretation uses. Event searches (stations, ingresses, returns, quarters) are refined to ~1 second of time. Verified in CI against published eclipse dates, the 2026 equinox, NOVAS Sun positions, and an independent Placidus implementation.

Architecture

code

src/
├── ephemeris/        Astrology core — backend-agnostic
│   ├── engine.ts     EphemerisBackend interface + astronomy-engine adapter (the swap seam)
│   ├── index.ts      Charts, aspects, synastry, composite, progressions
│   ├── events.ts     Time searches: returns, stations, ingresses, aspect times, moon phases
│   ├── eclipses.ts   Eclipse searches with astrological context
│   ├── houses.ts     Whole-sign, equal, Porphyry, Placidus (semi-arc solver)
│   ├── points.ts     Mean lunar nodes, Black Moon Lilith
│   ├── sidereal.ts   Ayanamsa (Lahiri, Fagan/Bradley)
│   └── time.ts       IANA timezone → UTC conversion (no dependencies, uses Intl)
├── mcp/              Tool/prompt/resource definitions on @modelcontextprotocol/sdk
├── stdio.ts          Local entry — `npx auseklis`
└── index.ts          Remote entry — Cloudflare Worker, Streamable HTTP via @hono/mcp

The EphemerisBackend interface in engine.ts is the deliberate swap seam: a future Rust/WASM clean-room ephemeris only needs to reimplement that one interface.

Development

bash

npm install
npm run typecheck   # strict TS
npm test            # 20-check smoke suite (ephemeris references + MCP end-to-end)
npm run build       # emit dist/
npm run dev         # local Cloudflare Worker on :8787
npx @modelcontextprotocol/inspector node dist/stdio.js   # poke tools interactively

See docs/tools.md for the full tool reference and docs/architecture.md for design notes.

Licensing

MIT. This project deliberately avoids the Swiss Ephemeris (.se1/.se2 data files and the sweph bindings): those are AGPL-licensed, which would impose AGPL obligations on any network service built on them. Everything here is computed from MIT-licensed code with no external data files — safe to embed, fork, and deploy commercially. Details in NOTICE.

The trade-off: no Chiron or asteroids (they need ephemeris data files). They are on the roadmap via public-domain JPL-derived data.

Roadmap

v1: Rust/WASM clean-room ephemeris backend behind the same EphemerisBackend seam
Chiron + major asteroids from public-domain JPL data
Koch houses, declination/parallel aspects

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "auseklis": {
      "command": "npx",
      "args": [
        "-y",
        "auseklis@0.2.2"
      ]
    }
  }
}