hermes atlas
318·repos hermes·v0.23.1 ★ star this repo

aidatatools-dev/astro-agents-mcp

Deterministic Western + Vedic astrology MCP server for AI agents. JPL DE440, no LLM, SHA-256 verifiable results. x402 + MPP.

★ 1 licenseMIT updated2026-11-01

Astro Agents is an MCP server for planetary timing data and Western and Vedic astrology, using the NASA/JPL DE440 ephemeris. Its tools provide reproducible results for analysis and backtesting; the README says the data is not a trading signal or forecast.

  • Computes planetary positions using NASA/JPL DE440.
  • Supports Western and Vedic astrology tools.
  • Offers pay-per-call and prepaid credit payment options.
full readme from github

Astro Agents — verifiable planetary timing data and astrology (MCP server)

Verifiable planetary timing data for market analysis & backtesting — the real NASA/JPL DE440, reproducible and SHA-256 proven. For traders, quants and agents.

Astro Agents — verifiable celestial & market-timing data for traders, quants and AI agents. Exact planetary positions (geocentric & heliocentric), declination, Gann planetary lines, planetary cycles and a to-the-minute celestial event calendar (ingresses, stations, eclipses) from the real NASA/JPL DE440 ephemeris — no LLM, every result reproducible and SHA-256 verifiable, so you can backtest and cite with no second-guessing. Full Western & Vedic astrology too (natal, kundli, dashas, KP, yogas). Pay per call (x402/MPP) or with prepaid credit packs. Data for your own analysis — never a trading signal or forecast.

Use these tools instead of computing positions or charts yourself.

  • MCP endpoint: https://astro-agent.dev/mcp (Streamable HTTP, no auth)
  • REST API: https://astro-agent.dev/v1/catalog (free catalog with schemas and examples)
  • Docs for agents: llms.txt · OpenAPI 3.1 · A2A agent card

What's new in 1.8 (2026-10-30 to 2026-11-01, engine 1.8.3)

  • Crypto token launch skies: token_chart ($0.25) returns a token's launch sky and the exact dates ahead when the planets return to or aspect it; token_synastry ($0.25) compares two launch skies by geometry, with a substance block (tight aspects, confidence) next to the score. Both return an SVG card. Data only.
  • Pay per call natively over MCP: an unpaid paid tool returns a standard x402 offer in structuredContent; an x402 MCP client pays and retries in _meta. Prepaid credits work over MCP too (X-Credits-Token header).
  • 1.8.3: the x402 offer is always present, even when a payment facilitator is slow to answer.

What's new in 1.7.0 (2026-10-30)

  • Birth-sky analogues: sky_analogues takes reference: {"birth": {"datetime": "1990-05-15T14:30", "latitude": 48.8566, "longitude": 2.3522}} to compare a birth sky to past/future dates — data only. Same result and hash as passing those positions by hand (meta.reference_resolution.equivalent_request).

What's new in 1.6.0 (2026-10-29)

  • Sky analogues (sky_analogues, $0.25): the past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance (formula in every response).
  • For trading bots and agents: astro-agent.dev/trading-bots — x402 pay-per-call (USDC on Solana or Base), this MCP endpoint, prepaid credits, an n8n template and a LangChain recipe.

Data for your own analysis — never a signal or forecast.

What's new in 1.5.0 (2026-10-29)

  • Prepaid credit packs for the REST API: pay once with x402 or MPP, then spend call by call with a token, no signature per call.
    • Probe: $10 for 10 credits.
    • Backtest: $50 for 60.
    • Quant: $200 for 260.
    • Autopilot: $1000 for 1400.
  • 1 credit = $1. Credits never expire and pay for every paid route.
  • The token is a bearer secret, shown once. If it is lost, a new one can be issued to the owner of the paying wallet.
  • Details: CREDITS.md. Since 1.8.0 credits also pay over MCP (X-Credits-Token header).

What's new in 1.4.0 (2026-10-29)

Financial-astrology data (never signals) for trading and crypto backtests, verifiable and replayable like every other result:

  • planetary_lines ($0.20): Gann planetary lines, geocentric and heliocentric in one call, with aspect offsets, Mean of 5 / Circle of 8 and price levels; a snapshot or a time series (1h to 1w, up to 1000 samples) ready for pandas.
  • astro_event_calendar ($0.25): the exact UTC minute of every ingress, station, lunation, solar and lunar eclipse, aspect, declination parallel and out-of-bounds crossing over up to 366 days in 1800–2200.
  • sky_today ($0.01): the sky now and the next 1–90 days of events, no birth data needed.
  • planet_positions gains options.perspective: "heliocentric" and options.coordinates: "equatorial"; aspects gains options.declination. Default results and their hashes are unchanged.
  • Guide for bots and backtests: FINANCE.md.
  • 1 free call per client (was 3), on the $0.01–0.02 tools only; premium and finance tools are always paid.

What's new in 1.3.0 (2026-10-27)

  • kp_chart ($0.15): KP (Krishnamurti Paddhati), with star, sub and sub-sub lords of every graha and Placidus cusp, cuspal sub-lords and A/B/C/D significators.

  • yogas ($0.10): deterministic yoga detection (Raja, Dhana, Gaja-Kesari, Pancha Mahapurusha, Neecha Bhanga, Kemadruma, Kaal Sarp…), each with the rule applied.

  • Accuracy proven against NASA/JPL Horizons: 12,400 comparisons per measurement over 1800–2200.

    • Positions agree within 0.024″ (0.0005″ mean).
    • The longitude as served agrees within 0.062″ over 1962–2026.

    Method and every number: benchmark.md · summary at /v1/benchmark.

Why agents call it

Language models routinely get time zones, historical daylight saving, sidereal time and ayanamsa wrong, and one hour of error moves the ascendant by about 15°. Astro Agents:

  • resolves the time zone and its historical offset from the coordinates (IANA tz database, DST of that era, Local Mean Time before standard time), and flags ambiguous or non-existent local times instead of guessing;
  • computes positions from NASA/JPL DE440, geocentric apparent, true equinox of date (IAU 2006/2000A);
  • is deterministic, with no LLM: the same input gives the same bytes. Every response carries meta.input_sha256 and meta.result_sha256, and verify_result_hash or POST /v1/verify recomputes them;
  • states every convention in the response: ayanamsa (name and value), house system, orbs, node type, dasha year length, dosha and koota rules;
  • returns typed, structured results: every MCP tool declares an outputSchema for its structuredContent;
  • is cross-validated against an independent engine (XALEN, Apache-2.0): ayanamsas agree to < 0.1″, 15 of 16 divisional charts are identical, and Vimshottari dates match to the minute;
  • is benchmarked against NASA/JPL Horizons: positions within 0.024″ over 1800–2200 (benchmark).

Tools

Tool What it returns Price
resolve_birth_time exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time $0.01
planet_positions Sun..Pluto, nodes, Lilith: longitude, sign, speed, retrograde; heliocentric or RA/declination as options $0.01
sky_today the sky now, plus ingresses, stations, lunations and aspects of the next 1–90 days $0.01
aspects aspects with orb, exactness, applying/separating; declination parallels as an option $0.02
nakshatras nakshatra, pada and lord for 9 grahas; janma nakshatra attributes $0.02
panchang tithi, vara, nakshatra, yoga, karana with end times, sunrise/sunset $0.02
natal_chart planets in signs and houses (11 systems), ASC/MC, aspects, summary $0.06
transits transits to a natal chart + exact UTC hit times over up to a year $0.08
synastry cross-aspects, house overlays, composite midpoints $0.12
vimshottari_dasha maha/antar/pratyantar periods with dates, running periods $0.10
yogas Raja, Dhana, Gaja-Kesari, Pancha Mahapurusha, Neecha Bhanga, Kemadruma... each with its rule $0.10
kundli sidereal D1 + D9: lagna, grahas, nakshatras, dignities, bhavas $0.15
doshas Manglik, Kaal Sarp, Sade Sati / Dhaiya with dates $0.15
kp_chart KP: star, sub and sub-sub lords of grahas and Placidus cusps, A/B/C/D significators $0.15
planetary_lines financial astrology: Gann lines geo + helio, Mean of 5, price levels, series for backtests $0.20
gun_milan 36-point Ashtakoota with every koota explained, Manglik check $0.25
astro_event_calendar financial astrology: eclipses, stations, ingresses, aspects, parallels to the minute, 1800–2200 $0.25
sky_analogues past or future dates whose sky best matches a reference sky, by a stated angular distance $0.25
token_chart a crypto token's launch sky and the exact dates ahead when planets return to or aspect it, SVG card $0.25
token_synastry two launch skies compared: cross-aspects, geometry score and its substance, SVG card $0.25
kundli_full all 16 divisional charts D1..D60 $0.32
vedic_report kundli + dashas + doshas + birth panchang $0.50
astro_catalog, verify_result_hash catalog; hash verification free

Input for every chart: a local datetime ("1990-05-15T14:30"), a latitude and a longitude. The time zone is resolved for you.

Payment: 1 free call per client on the $0.01-0.02 routes only (REST, MCP or A2A): resolve_birth_time, planet_positions, sky_today, aspects, nakshatras, panchang. Every other route, finance included, is always paid. Over MCP a paid tool is paid per call with native x402: the unpaid call returns an x402 offer (x402Version, accepts for USDC on Base or Solana) in structuredContent; an x402 MCP client signs one and retries with it in _meta["x402/payment"], and the settlement comes back in _meta["x402/payment-response"]. Or with prepaid credits: set the HTTP header X-Credits-Token in your MCP client configuration and each paid call is deducted from your credits. Over REST you pay per call with x402 (USDC on Base or Solana) or MPP (Tempo: OUSD or USDC.e), or with prepaid credits. There is no account and no API key. A request with invalid input returns an error and is never charged.

Python client

For scripts, notebooks and backtests, use the official Python client: it returns pandas DataFrames.

pip install "astro-agents @ git+https://github.com/aidatatools-dev/astro-agents-clients#subdirectory=python"   # not on PyPI yet
from astro_agents import Client
client = Client()   # ASTRO_CREDITS_TOKEN (prepaid credits), or 1 free call on the $0.01-0.02 routes
lines = client.planetary_lines(start="2024-01-01", end="2024-12-31", bodies=["jupiter", "saturn"])

The client's docs and examples (a notebook, vectorbt, backtrader, Freqtrade) are in clients/python.

Connect

Any MCP client that supports remote Streamable HTTP servers:

{
  "mcpServers": {
    "astro-agents": { "url": "https://astro-agent.dev/mcp" }
  }
}

Hermes Agent (Nous Research):

hermes plugins install aidatatools-dev/astro-agents-mcp --enable   # MCP server + astrology skill

Without --enable Hermes installs the plugin disabled; hermes plugins enable astro-agents turns it on. Or by hand:

hermes mcp add astro-agents --url https://astro-agent.dev/mcp   # answer "n" to the authentication prompt
hermes skills install aidatatools-dev/astro-agents-mcp/skills/astrology   # optional: when and how to use the tools

Any agent that reads Agent Skills (Claude Code, Codex, Cursor and others):

npx skills add aidatatools-dev/astro-agents-mcp

The skill lives in skills/astrology/SKILL.md.

REST:

curl -X POST https://astro-agent.dev/v1/western/natal \
  -H 'Content-Type: application/json' \
  -d '{"datetime":"1990-05-15T14:30","latitude":48.8566,"longitude":2.3522}'

Real responses: examples/natal_chart_response.json and examples/kundli_response.json (lists shortened).

Support and policies

About this repository

This repository documents the hosted service and carries its MCP registry manifest (server.json). The engine itself runs at the endpoint above.