Caelus Mcp

io.github.heavyblotto由 GitHub 账号 heavyblotto 发布v0.24.1更新于 Oct 24, 2026

34-tool Caelus MCP for validated astrology: charts, transits, Vedic, facts, sky view, synthetic.

已验证Streamable HTTP可网页运行

概览

AI 生成的概览

一个占星计算服务器,让助手排本命盘与事件盘、计算行运、吠陀与希腊化技法,以及天空视图画面。

可以做什么
排盘与比较:本命盘、当前天象、合盘、中点盘与戴维森盘、返照盘、推运,以及扰动盘和相似天象,并给出可引用的排序星盘事实与结构特征。计算时间与事件:行运、相位日期、升落、月相、日月食与留等天象、行星时、月亮空亡,以及择时排序。应用传统与希腊化技法:尊贵、赫尔墨斯点、小限、法达、黄道释放、主限方向、偕日升与相位格局。应用吠陀方法:宿、大运周期、分盘与瑜伽。取景天空:为图像提示生成天空视图与天空视图序列,并支持合成天体系统。
适用场景
当助手需要计算出的星盘与派生事实而非自由解读时使用,例如本命解读、行运与择时、吠陀或希腊化分析,或生成天空视图图像提示。适合希望获得结构化、可引用星盘数据的用户。
运行要求
可作为远程端点运行,也可作为本地 npm 包通过 stdio 运行,本地安装需要 Node.js。未声明认证、环境变量或请求头。星盘工具需要出生日期、时间、纬度和经度;天象工具需要地点。
安装前请注意
工具返回计算出的位置与计数,而非解读,解读取决于助手。出生日期、时间与地点属于个人信息,会发送到服务器。部分工具在未给地点时默认使用地心位置,使宫位与轴点仅为名义值。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Caelus Mcp,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.heavyblotto%2Fcaelus-mcp/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "caelus": {
      "type": "http",
      "url": "https://www.ephemengine.com/api/mcp"
    }
  }
}

README

Caelus

Clean-room astrology computation monorepo. MIT, no Swiss Ephemeris code, no AGPL, no ephemeris files. Caelus computes ephemeris positions, charts, events, hellenistic timing techniques, Vedic methods, citable chart facts, sky-view image-prompt frames, and the MCP tools around them. Live at ephemengine.com.

Packages

PathnpmDescription
packages/caeluscaelusTypeScript engine (~153 KB gzipped total, zero deps)
packages/caelus-mcpcaelus-mcpMCP server: charts, transits, synastry, events, eclipses
packages/caelus-delineations-pd—Public-domain interpretation corpus + default validation set for interpret()
packages/birthcaelus-birthBirth time + place → UT (timezone and DST resolution)
packages/wheelcaelus-wheelReact SVG chart wheel, zero runtime deps
apps/web—Next.js site: playground, validation, edge /api/chart
caelus-starter—Next.js starter app (separate repo)

The Python reference engine and data-fitting pipeline live in python/; they mint the coefficient data and golden fixtures and are not a runtime dependency.

Docs

Quick start

bash
npm installnpm run buildnpm testnpm run dev -w web

http://localhost:3000 — live chart in the browser. Edge API: GET /api/chart?date=…&lat=…&lon=….

Branches

  • main — stable releases
  • dev — active development

来源:README.md,提交 b5631d4

工具

35

natal_chart

A person's birth chart. Requires their exact birth date+time and birthplace (all three: date, lat, lon). Use this — not current_sky — whenever the question is about someone's natal/birth chart. Returns 13 bodies (sun–pluto, chiron, nodes) with sign, house, retrograde, speed; ASC/MC; cusps; major aspects with orb, applying/separating phase, and strength (1=exact). Vs Swiss Ephemeris (1850–2150): Sun–Saturn ≤1″, Uranus ≤1.9″, Neptune ≤4.6″, Moon ≤2.5″, Pluto ≤3.4″ (Chebyshev pack), Chiron ≤1″, mean node ≤1″, true node ≤ 1′ vs SE's built-in ephemeris.

输入参数lat必填lon必填date必填gridoutputzodiacremaindersseparationhouse_system

current_sky

The sky at a moment and place — not tied to any person. Use for "what's the sky/transits right now" or the chart of a non-birth event. Date defaults to now; lat/lon default to 0,0 (geocentric on the equator at the prime meridian), where houses and ASC/MC are nominal — pass a real location if houses matter. For a specific person's birth chart use natal_chart instead. Returns positions, houses, retrogrades, aspects.

输入参数latlondategridoutputzodiacremaindersseparationhouse_system

sky_view

Where the visible bodies land in a framed photo of the sky, for an image prompt. Give a place, a moment, an aim (compass direction and altitude), a lens, and an image size; get each in-frame body's pixel position, apparent size, brightness, the Moon's phase orientation, a sky-state summary (twilight, limiting magnitude, horizon row), the bright bodies just outside the frame, a ready-to-use prompt, and a machine-readable `renderPlan` (a body-free background-plate prompt plus the computed layers to composite locally, for a hybrid render pipeline). Caelus computes the geometry and photometry; it does NOT render the image. For "at sunset", first find the set time with sky_events, then pass it as date.

输入参数lat必填lon必填datelenswidthbortleheightazimuth必填altitudeoverlaysdeep_fieldelevation_m另有 2 个

sky_view_sequence

A time sequence of sky frames for an animation: the same place, aim, and lens stepped through time. Returns a compact per-frame timeline (instant, twilight, Sun/Moon altitude, Moon phase + bright-limb, whether the Milky Way is in frame) plus the fixed celestial pole and the sky's sidereal rotation per frame. Each frame's full pixel-accurate spec comes from calling sky_view at that instant; this tool plans the timeline. Use for sunset-to-night transitions, star-trail planning, or Moon-phase progressions.

输入参数lat必填lon必填datelenswidthbortleframes必填heightazimuth必填altitudestep_minutes必填

synthetic_validate

Check an authored synthetic celestial system for ill-defined inputs: duplicate body ids, non-positive periods, out-of-range eccentricity, or a dangling observer. Returns `impossible` and a list of problems — the same honesty pattern as compileForm.

输入参数system必填

synthetic_positions

Positions of every body in an authored synthetic system at one instant. Three body modes: `placement` (fixed longitude), `periodic` (uniform motion), `kepler` (constant elements). With `observer` set on the system, positions are geocentric/apparent from that body (outer bodies can show retrograde). Pass `t_days` for abstract day units, or `date` (UT ISO) when body `epoch` values are Julian Days. Returns speed and retrograde per body.

输入参数datesystem必填t_days

synthetic_sky_view

Sky View for a mix of real and synthetic bodies: register the authored system on an ephemeral engine, then frame the visible sky like sky_view. Synthetic bodies can carry render attributes (sizeDeg, magnitude, color) that flow into the pixel spec and prompt. Real Sun/Moon/planets stay for twilight and context unless omitted from `bodies`.

输入参数lat必填lon必填datelenswidthbodiesbortleheightsystem必填azimuth必填altitudeelevation_m另有 1 个

transits

Transiting planets vs natal chart: aspects within orb (applying/separating), natal house per transiting body.

输入参数lat必填lon必填orbdate必填zodiachouse_systemtransit_date

synastry

Compare two people's birth charts: inter-chart aspects with orbs, house overlays both ways, plus ranked citable fact atoms and a ready `brief` (synastry/composite ids for auditCitations). Each person needs date+lat+lon. House overlays always use Placidus (not configurable here).

输入参数a必填b必填orbzodiac

find_aspect_dates

Exact dates a transiting body makes an aspect, within a range: to a fixed longitude OR to another transiting body. Provide exactly one of target_lon / target_body. Includes retrograde re-hits. Body names are snake_case (mean_node, true_node).

输入参数end必填body必填start必填aspect必填zodiactarget_lontarget_body

rectification_grid

Rectification sweep: ASC/MC at each step across a window of UTC hours on one date, with ASC sign-change times. Use when the birth time is unknown and you want candidate times. The sweep runs over window_start_hour..window_end_hour (UTC hours of the given date); the date's time portion is ignored.

输入参数lat必填lon必填date必填step_minuteswindow_end_hourwindow_start_hour

sky_events

Sky events in a UTC date range: rise/set/meridian transits (need lat+lon+body), lunar phases (new/quarters/full), solar and lunar eclipses, stations (body turns retrograde/direct; needs body), zodiac degree crossings (needs body + target_lon). Solar eclipses report global circumstances (type, magnitude, gamma) plus the greatest-eclipse location and path width; add lat+lon to also get local circumstances (type seen, magnitude, obscuration, contact times C1-C4). Lunar eclipses report type and magnitude; add lat+lon to learn whether the Moon is above the horizon there. Times to the second vs Swiss Ephemeris (stations to ~1 min: ill-conditioned by nature). Range <= 370 days.

输入参数end必填latlonbodykinds必填start必填zodiactarget_lon

planetary_hours

Planetary hours for a moment and place: the unequal hour in effect (its ruler, day/night, hour number 1-24, start/end UTC), the ruler of the planetary day, and the full 24-hour ruler sequence. Hours split the day (sunrise to sunset) and night (sunset to next sunrise) into twelve each; the day ruler is the weekday ruler and the hours follow the Chaldean order. Needs lat+lon. Returns available:false above the polar circles when the Sun does not rise or set that day.

输入参数lat必填lon必填date

void_of_course

Void-of-course Moon at a moment: whether the Moon makes no further Ptolemaic aspect to a traditional planet (Sun..Saturn) before it leaves its current sign. Returns the Moon's sign, the UTC time it exits that sign, and the UTC time of its next perfecting aspect (null when none remains -- i.e. void). Tropical by default.

输入参数datezodiac

returns

Solar or lunar return: the instant(s) a body returns to its natal longitude within a window, plus the full return chart for the first one. The Sun returns about yearly (the solar-return chart for the year), the Moon about monthly. Return chart is cast for the return moment at return_lat/return_lon (defaults to the birthplace; pass the current/relocated place for a relocated return).

输入参数lat必填lon必填body必填date必填gridoutputzodiacremaindersreturn_latreturn_lonsearch_end必填house_system另有 1 个

progressions

Secondary progressions (day-for-a-year) and solar-arc directions of a natal chart to a target date. Returns, per body, the secondary-progressed longitude and the solar-arc-directed longitude, plus the solar arc itself. Longitudes only (no houses), so no birthplace is needed.

输入参数date必填zodiactarget_date必填

composite

Relationship charts for two people: the midpoint composite (each body and angle is the shorter-arc midpoint of the two natal positions) and the Davison chart (a real chart cast for the midpoint in time and place). Each person needs date+lat+lon.

输入参数a必填b必填zodiachouse_system

dignities

Essential dignity and sect for the seven traditional planets at a moment and place. Per planet: its sign, any essential dignity (domicile/exaltation/detriment/fall), its weighted essential-dignity score (Lilly: rulership 5, exaltation 4, triplicity 3, term 2, face 1; detriment -5, fall -4) with a peregrine flag, its planetary sect (diurnal/nocturnal, null for Mercury), and whether it is in sect given a day or night chart. The chart is day when the Sun is above the horizon — so lat+lon are required.

输入参数lat必填lon必填date必填zodiac

lots

The seven Hermetic lots (Arabic parts) — Fortune, Spirit, Eros, Necessity, Courage, Victory, Nemesis — cast from the Ascendant and reversing direction by sect (a chart is day when the Sun is above the horizon). Per lot: its longitude and zodiacal position. Lots are anchored to the Ascendant, so an exact time and lat+lon are required. Fortune and Spirit are mirror images about the Ascendant. Tropical by default.

输入参数lat必填lon必填date必填zodiac

profections

Annual and monthly profections (a Hellenistic time-lord technique) at a target date. The natal Ascendant advances one whole sign per year of life; the profected sign's traditional ruler is the lord of the year, the single most important time-lord for that year. Returns the age in years, the month within the profection year, and the annual and monthly profected sign (with its whole-sign house from the natal Ascendant and its lord). Needs the birth time and place for the Ascendant.

输入参数lat必填lon必填date必填zodiactarget_date必填

firdaria

Firdaria (firdariyyat): the Persian/medieval planetary time-lord periods. Life divides into nine major periods totalling 75 years — the seven planets (a day chart starts with the Sun, a night chart with the Moon) then the North and South Nodes — each planetary period split into seven sub-periods. Returns the full timeline (each period and sub-period with UTC start/end) and, when target_date is given, the major and sub lord active then. Sect is taken from the birth chart, so lat+lon are required; pure time arithmetic, no zodiac.

输入参数lat必填lon必填date必填target_date

releasing

Zodiacal releasing (aphesis), the Hellenistic time-lord technique from Vettius Valens, released from a Lot (Spirit by default, or Fortune). From the Lot's sign, periods release sign by sign with planetary minor-year lengths on the 360-day-year convention; each level is a twelfth of the one above (L1..L4), and a loop back to the starting sign looses the bond, jumping once to the opposite sign (+6). Returns the timeline down to max_level over the horizon and, when target_date is given, the L1..L4 lords active then. Anchored to the natal Lot, so an exact time and lat+lon are required.

输入参数lat必填lon必填lotdate必填zodiacmax_leveltarget_datehorizon_years

directions

Primary (mundane) directions of the seven traditional planets to the four angles (MC, IC, Ascendant, Descendant), and optionally between the planets themselves. The diurnal rotation carries a body to the angle (or a promissor to a significator); the arc of rotation, converted by a time key (Naibod 0.9856473°/yr by default, or Ptolemy 1°/yr), gives the age of the direction. Returns the directions within max_years, sorted by age, each with its arc, age in years, and UTC date. With include_mundane, also returns the planet-to-planet (promissor → significator) directions. Circumpolar bodies have no Ascendant/Descendant directions. Needs the birth time and place; equatorial, so zodiac is irrelevant.

输入参数keylat必填lon必填date必填max_yearsinclude_mundane

nakshatras

The nakshatra (one of the 27 lunar mansions of 13°20′) of each classical point on the sidereal zodiac: the seven traditional planets and the Ascendant (lagna). Per point: the nakshatra name, its pada (quarter, 1–4), the ruling planet (the Vimshottari lord), and degrees into the nakshatra. The Moon's nakshatra (janma nakshatra) anchors the Vimshottari dasha. Sidereal by definition; Lahiri ayanamsa by default. Needs the birth time and place for the Ascendant.

输入参数lat必填lon必填date必填zodiac

dasha

Vedic dasha periods — planetary time-lord cycles started from the Moon's birth nakshatra. system selects Vimshottari (120-year, the standard), Yogini (36-year, eight yoginis), or Ashtottari (108-year). Returns the period timeline (mahadasha → antardasha) with UTC start/end, the balance of the first period at birth, and — when target_date is given — the lords active then (Vimshottari also gives the pratyantardasha). Sidereal; Lahiri by default. Needs the birth time and place.

输入参数lat必填lon必填date必填levelssystemzodiactarget_date

vargas

Parashari divisional charts (vargas): the sign of each of the seven planets and the Ascendant in the requested D-charts — D1 rasi, D2 hora, D3 drekkana, D9 navamsa, D10 dasamsa, D12 dwadasamsa, D30 trimsamsa. Per point in each chart: the divisional sign and the division number within the rasi. The navamsa (D9) is the most consulted after the rasi. Sidereal; Lahiri by default. Needs the birth time and place for the Ascendant.

输入参数lat必填lon必填date必填zodiacdivisions

yogas

Vedic yogas (planetary combinations) on the sidereal rasi chart: the five Pancha Mahapurusha yogas (Ruchaka, Bhadra, Hamsa, Malavya, Shasha), Gajakesari, Budha-Aditya, and Chandra-Mangala; whether Kemadruma (the isolated-Moon yoga) is present; the raja yogas (a kendra lord associating with a trikona lord) and dhana (wealth) yogas, each as the lord pair and how they associate (conjunction, aspect, or exchange); and the chart's yogakarakas (a planet ruling both a kendra and a trikona). Sidereal; Lahiri by default. Needs the birth time and place.

输入参数lat必填lon必填date必填zodiac

aspect_patterns

Classical aspect configurations in a chart: T-squares, grand trines, grand crosses, yods, kites, mystic rectangles, and stelliums by sign and by house. Each is a structured object with the participating bodies and the worst defining-aspect orb; T-squares and yods also name the apex, stelliums their sign or house. Reported patterns are maximal — a grand cross hides the T-squares it contains, a kite its grand trine. Pure geometry (engine orbs plus a quincunx for yods), no interpretation. Needs date, lat, lon.

输入参数lat必填lon必填date必填zodiachouse_system

parans

Parans (paranatellonta): co-angular bodies over the 24 hours from a date at a latitude — every pair of bodies simultaneously on one of the four angles (rising, culminating, setting, anti-culminating) within a stated tolerance. The relationship behind Brady's fixed-star parans, computed for the moving bodies; pure positional astronomy over the validated rise/set/transit times. Longitude-independent: latitude alone fixes the geometry, so only lat is needed. Date defaults to now.

输入参数lat必填datebodiesoutputtolerance_min

chart_signature

A chart's structural signature as plain counts: element, modality, angularity, quadrant, and hemisphere distributions over the bodies; the dominant element, modality, and most-occupied sign; and the classical chart ruler (the ruler of the Ascendant's sign). Counts only, no interpretation — a compact summary for emphasis and comparison. Needs date, lat, lon.

输入参数lat必填lon必填date必填zodiachouse_system

chart_facts

A chart's validated facts as ranked, citable atoms for interpretation. Each fact has a stable id (e.g. "aspect:moon~neptune:conjunction"), the bodies it concerns, a salience score (luminaries, angular placements, the chart ruler, tight/hard aspects, configurations rank high), and a plain-language statement. Facts span placements, aspects, configurations, the structural signature, dispositors and receptions, a body's tight conjunction with a bright fixed star (e.g. "star:jupiter:Sirius"), and the Part of Fortune and Spirit (e.g. "lot:fortune"). Read the facts, write the interpretation in your own words, and cite the [id] each statement rests on — do not introduce facts not listed. Returns the ranked facts plus a ready-to-interpret `brief`. By default a real birth chart: pass date+lat+lon. The chart's grounding is first-class via `realm` (what it is: observed/forecast/fictional/mythic/archetypal/…) and the time: an exact `date`, an uncertain `earliest`+`latest` range (the brief then frames it as provisional and trusts the Moon/angles/houses less), `constraints` for an archetypal chart with no time (synthesized via the compiler), or a full structured `when` (relative-to-another-event or a narrative calendar). A `when` of kind `relative` looks its `anchorId` up in `anchors` (a map of id → UTC instant supplied in the request). Omit lat+lon for a placeless chart (nominal houses).

输入参数latlondatewhenlimitplacerealmwherelatestzodiacanchorsearliest另有 5 个

counterfactual_chart

A birth chart, perturbed — a 'what if'. Give a base chart (date+lat+lon) and an edit: `shift_time` (e.g. '1h', '-30m', 'P1D') moves the instant ("born an hour later"), `move_lat`+`move_lon` recompute at another place, and/or `set_longitudes` moves bodies to new ecliptic degrees ("Mars in the next sign"). Returns the diff vs the original: bodies that changed sign or house, aspects gained or lost, and angles that changed sign. A time/place edit rotates the houses and angles while planets stay put; a longitude splice moves only those bodies and recomputes their aspects.

输入参数lat必填lon必填date必填zodiacmove_latmove_lonshift_timehouse_systemset_longitudes

similar_skies

Find when the sky most resembled a reference moment. Builds a feature vector for the reference date's planetary configuration and scans a window for the closest matches by cosine similarity (1.0 = identical configuration). Answers 'when did the sky last look like this?' for transit echoes and historical analogues. Returns the top matches with their similarity, highest first.

输入参数end必填limitstart必填step_daysreference_date必填

cosmic_weather

The mundane sky on a date: the active aspect configurations among the transiting planets (T-squares, grand trines, grand crosses, yods, kites, mystic rectangles, stelliums by sign), any planet stationing within a window, and whether the Moon is void of course. A 'cosmic weather' snapshot; no birth chart or location needed.

输入参数date必填zodiacwindow_days

版本历史

1
  1. v0.24.1最新Sep 16, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分