Content
# 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](#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, Part of Fortune, 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 · Part of Fortune (classical day/night formula).
## 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](https://github.com/igmizo/auseklis/releases) 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.
## Library usage
The ephemeris core (everything under `src/ephemeris/`) is importable directly — no MCP client or subprocess needed. This is the right shape for serverless runtimes (Vercel, Workers), where spawning `npx auseklis` per request is not an option:
```ts
import { computeNatalChart } from "auseklis/ephemeris";
import { findRetrogradePeriods } from "auseklis/ephemeris/events";
import { findEclipses } from "auseklis/ephemeris/eclipses";
const chart = computeNatalChart({
utc: "1990-03-15T13:45:00Z",
location: { latitude: 56.95, longitude: 24.11 }, // Riga
houseSystem: "placidus",
});
```
`auseklis/ephemeris` carries the chart math (natal, transits, synastry, composite, progressions, single positions, angles) plus `resolveInstant` for local-time → UTC conversion; `…/events` and `…/eclipses` carry the time-domain searches. Fully typed, ESM only, no data files.
## 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](https://github.com/cosinekitty/astronomy) (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
```
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 # 23-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](docs/tools.md) for the full tool reference and [docs/architecture.md](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](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
