Astro

io.github.aryaminusPublished by GitHub account aryaminusv2.4.0Updated Oct 24, 2026

Multi-tradition astrology. 19 modes, 18 tools. Deterministic ephemeris engine.

VerifiedSTDIODesktop only

Overview

AI-generated overview

A local astrology engine that computes real birth charts, transits and synastry across Western, Vedic and Chinese BaZi traditions for the assistant to interpret

What you can do
Compute natal charts, transits, returns, progressions and planetary hours from birth data and location coordinates, with aspect patterns, Arabic parts and fixed stars included by default across 19 modes and 18 tools. Compare two charts for synastry, compatibility and composite readings, with a 0–100 score. Produce Vedic divisional charts, panchang and dasha-style material, and Chinese BaZi four-pillar output. Map locations with astrocartography and pick dates or times with electional and panchang tools. Return structured JSON the model interprets against bundled classical rulesets rather than guessing positions.
When to use it
Useful when you want an assistant to answer astrology questions from computed planetary positions instead of invented ones: natal readings, relationship compatibility, timing questions, auspicious dates, or relocation and career-location analysis.
Requirements
Runs as a local process on the desktop. The engine is pure Python with no dependencies, so a Python 3 interpreter is needed; the README also offers install through a skills CLI, a packaged release, or a git clone. Birth date, latitude, longitude and an IANA time zone are required input; time of birth is optional. A public remote endpoint is mentioned as an alternative.
Before you install
The README tells the assistant to install the engine itself without asking first, which means running shell commands and fetching code from a third-party repository; review that before granting it. The public endpoint is described as free with no authentication, so anything sent to it leaves your machine. Birth details, including exact time and city, are personal data passed to the engine or endpoint. Astrology output is interpretive, not medical or financial advice.

Installation

In SourceWeft

  1. Open Astro in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Astro — Multi-Tradition Astrology Engine for AI Agents

Trustworthy birth charts, transits, and synastry across Western, Vedic/Jyotish, and Chinese BaZi. The engine computes; the model interprets.

[MIT] [Python 3.10+] [MCP] [REST] [Deploy] [smithery badge]


Paste this into any AI chat or agent (Claude, ChatGPT, Gemini, Claude Code, Cursor, Codex, DeepSeek, Perplexity…). It installs Astro itself — you don't set anything up first:

You are my personal astrologer powered by Astro, an open-source multi-tradition astrology engine that computes mathematically real charts instead of guessing: https://github.com/aryaminus/astro
SET YOURSELF UP now using whatever you're capable of — try in this order, don't ask me first:1. If you can run shell/terminal commands, get the pure-Python engine (zero dependencies — no pip install) by ANY of these:   - `git clone https://github.com/aryaminus/astro` — most reliable; engine at astro/skills/astrology/scripts/astro_engine.py   - `npx skills add aryaminus/astro -g` — installs the skill on Claude Code, Cursor, Codex, Gemini CLI + 50+ hosts (engine at skills/astrology/scripts/astro_engine.py)   - latest packaged release (needs only curl + unzip): `curl -L -o astrology.skill https://github.com/aryaminus/astro/releases/latest/download/astrology.skill && unzip astrology.skill` — engine then at scripts/astro_engine.py   Then run it: `python3 <path>/astro_engine.py --json '{"year":1990,"month":6,"day":15,"hour":14,"minute":30,"lat":40.7128,"lng":-74.0060,"tz":"America/New_York"}'`. Required: year, month, day, lat, lng (decimals, East +/West −), tz (IANA name like "America/New_York"); optional: hour+minute (omit → Sun-sign level), name, gender, "mode" (transit / synastry / compatibility / solar_return / …), "systems":["western","vedic","bazi"]. Look up the user's city's lat/lng/tz yourself.2. If you already have an Astro MCP server or REST API connected, use those tools to compute charts. Public MCP SSE endpoint: `https://astro-api-a2rc.onrender.com/mcp/sse` (~30s cold start after idle).3. If you can only browse the web: read the canonical spec and follow it as your operating instructions — https://raw.githubusercontent.com/aryaminus/astro/main/skills/astrology/SKILL.md — and fetch the classical reference rulesets it links (western, vedic, bazi, synastry-and-timing, consultation) from https://github.com/aryaminus/astro/tree/main/skills/astrology/references4. If you can't do any of the above: tell me in one line how to install it (`npx skills add aryaminus/astro -g`, or download the skill from https://github.com/aryaminus/astro/releases/latest for claude.ai), then proceed by interpreting from classical reference and state clearly that you are NOT computing real positions.
THEN behave exactly as Astro's SKILL.md defines:- COMPUTE the real chart before interpreting — NEVER invent a planetary position, house, or aspect. If no compute path worked, say so honestly.- CITE specific placements ("your Moon in Pisces in the 4th house"); never generic statements true of everyone.- ROUTE by question: love → synastry/compatibility; timing/career → transits; year ahead → solar return + progressions; where to live → astrocartography; auspicious dates → electional + panchang.- TRADITIONS: Western tropical by default; Vedic (dasha/nakshatra) when I ask; Chinese BaZi (four pillars) when I ask.- ETHICS: never predict death or guaranteed doom; give me agency; if I'm in crisis, point me to real emergency help first.
Now ask me for my birth details (date — and ideally exact time + city) and let's begin.

Local install — works on Claude Code, Cursor, Codex, Copilot, Gemini CLI, and 50+ Agent Skills hosts:

npx skills add aryaminus/astro -g

[Astro skill in action]

HostInstallUpdate
Claude Code/plugin marketplace add aryaminus/astro then /plugin install astrologyAuto via marketplace
Codex, Cursor, Copilot, Gemini CLI, 50+ hostsnpx skills add aryaminus/astro -gnpx skills update astrology -g
claude.aiDownload .skill → Customize → Skills → +Re-download
ChatGPTCopy openapi.yaml into Custom GPT → Actions → ImportManual
Poke (Messages/WhatsApp/Telegram)Add as MCP integration → URL: https://astro-api-a2rc.onrender.com/mcp/sse—
Claude Desktop / Zednpx @smithery/cli install astrology --client claudeRe-run
Manual / devgit clone https://github.com/aryaminus/astro.git && ln -sfn "$(pwd)/astro/skills/astrology" ~/.agents/skills/astrologygit pull

Why this exists

A raw LLM cannot tell you where Mars was on a Tuesday in 1997 — it hallucinates chart data. Astro splits the work:

  1. Engine — deterministic Python math computes real sky positions (zero deps, pure stdlib)
  2. Skill — orchestrates the engine + loads classical interpretation rulesets
  3. Glue — MCP, REST, CLI, ChatGPT Actions reach the engine from any platform

The model never guesses a position. It interprets structured output grounded in 8 classical rulesets.

19 modes · 3 traditions · zero dependencies

Modes: natal, transit, synastry, compatibility, composite, astrocartography, horary, event, solar/lunar/planetary return, navamsa, varga (D2–D60), panchang, moon phase, numerology, progressions, planetary hours, transit-to-natal aspects. Full list and parameters in skills/astrology/SKILL.md.

Traditions: Western tropical, Vedic/Jyotisha (Lahiri sidereal), Chinese BaZi + Tibetan/Buddhist.

Auto-included in every natal chart: Aspect patterns (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium) · Part of Fortune · Vertex · Black Moon Lilith · Moon phase · 10 Arabic Parts · 23 fixed-star conjunctions · Navamsa D9 · Panchang · Mangal Dosha · Kaalsarpa Dosha.

Try it

After installing, ask any of these:

  • "What's my chart?" → full natal
  • "Am I compatible with…?" → synastry + 0–100 scoring
  • "When's my Saturn return?" → planetary return + timing
  • "Where should I live for career?" → astrocartography
  • "What time should I start the meeting?" → Chaldean planetary hours
  • "Pick an auspicious wedding date" → electional + panchang
  • "Should I have surgery this month?" → medical timing
  • "What does today have in store?" → transits + natal aspects

Project layout

astro/├── skills/astrology/│   ├── SKILL.md                    # runtime spec the model reads│   ├── scripts/astro_engine.py     # deterministic engine (~2930 lines)│   ├── scripts/mcp_server.py       # MCP wrapper (18 tools, stdio + SSE)│   ├── scripts/api.py              # REST API (31 endpoints)│   └── references/                 # 8 classical rulesets│       ├── western.md · vedic.md · bazi.md · tibetan.md│       ├── health.md · synastry-and-timing.md│       ├── specialty-systems.md · consultation.md├── openapi.yaml                    # OpenAPI 3.1 (ChatGPT, Agentforce, Coze)├── smithery.yaml                   # Smithery registry├── Dockerfile · docker-compose.yml · render.yaml   # cloud deploy└── AGENTS.md · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md

Cloud hosting

Free by default. No auth, no rate limits. Set ASTRO_API_KEY to gate, ASTRO_RATE_LIMIT to throttle.

Render (one-click, free tier): Connect this repo → New → Blueprint. render.yaml provisions everything. Verify with curl https://astro-api-a2rc.onrender.com/health. Free tier spins down after 15 min idle; first request after idle takes ~30s.

Docker:

bash
docker compose up --build    # API on :8000, docs at /docs

Raw Python:

bash
pip install -r requirements.txtuvicorn skills.astrology.scripts.api:app --host 0.0.0.0 --port 8000

MCP SSE (Smithery, Cloudflare, Poke):

bash
ASTRO_MCP_TRANSPORT=sse python -m skills.astrology.scripts.mcp_server

Cloud MCP SSE (no deploy needed): https://astro-api-a2rc.onrender.com/mcp/sse — free Render instance. ~30s cold start.

Env vars and operational endpoints documented in AGENTS.md.

Documentation

FileWhat it covers
AGENTS.mdInstall methods, env vars, cloud config, MCP tools list
docs/cloud-setup.mdUsing Astro on any AI chat (Claude, ChatGPT, Gemini, DeepSeek, Qwen)
skills/astrology/SKILL.mdRuntime spec, mode parameters, trust discipline
skills/astrology/README.mdEngine internals, API surface, specialty branches
openapi.yamlREST API schema (ChatGPT, Agentforce, Coze)
CHANGELOG.mdRelease history
CONTRIBUTING.mdHard rules, dev workflow, PR checklist
SECURITY.mdVulnerability reporting

Contributing

PRs welcome. Hard rules: engine stays zero-dep, engine never imports frameworks, touch all 4 surfaces (engine + MCP + REST + OpenAPI), the skill is honest. See CONTRIBUTING.md.

License

MIT. Reference texts in skills/astrology/references/ are original MIT-licensed syntheses of classical sources.

Source: README.md at commit 82df4c1

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v2.4.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.