cosine-astro-mcp

cosine-astro-mcp

用于西方（热带）占星计算的 MCP 服务：本命盘、行运、比较盘、水星逆行、年度推运和月相。

大模型不擅长推算某个日期的行星位置，往往会凭空猜测。此服务改为使用 astronomy-engine 星历离线计算行星位置，并向模型提供简洁的文本摘要和完整的 JSON 数据。无需 API 密钥、网络调用或账号。

由 COSINE 余弦 打造 — cosineastro.com，一个提供 AI 解读的出生星盘网站。此服务使用的正是该网站运行的同一套星盘引擎，并将其发布为 MCP 服务。

繁體中文說明

安装

需要 Node.js 20 或更高版本。

Claude Code

claude mcp add cosine-astro -- npx -y cosine-astro-mcp

添加 --scope user，即可在所有项目中使用。

Claude Desktop — 编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "cosine-astro": {
      "command": "npx",
      "args": ["-y", "cosine-astro-mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（针对单个项目）：

{
  "mcpServers": {
    "cosine-astro": {
      "command": "npx",
      "args": ["-y", "cosine-astro-mcp"]
    }
  }
}

任何支持 stdio 的其他 MCP 客户端也可采用相同方式：命令为 npx -y cosine-astro-mcp。

工具

所有工具均为只读，对于给定输入会产生确定性结果（日期默认为“现在”的情况除外）。

工具	返回内容
natal_chart	十颗行星（星座、度数、宫位、逆行状态、每日运动）、上升点和中天、十二宫宫头、带容许度及入相／出相状态的主要相位，以及元素和模式的平衡情况（含各自的主导项）。
transits	指定日期和时间的行星位置（默认：现在）；若提供本命盘，还会返回它们与本命行星、上升点和中天形成的相位（容许度默认为 2°），以及每颗行运行星所在的本命宫位。
synastry	两张星盘之间的交叉相位（行星和上升点）、每个人的行星落入对方宫位的情况，以及合相、和谐相位和挑战性相位的简单统计。
mercury_retrograde	与指定日期范围重叠的水星逆行时段：逆行前阴影期开始、留逆、留顺、逆行后阴影期结束（精度约为一分钟），以及两次留的度数。
annual_profection	指定年龄或日期对应的推运宫位和星座（从上升点起按整宫制计算）、年度主星及其本命位置，以及该推运年份的起止日期。
moon_phase	月相名称、照亮比例、日月角距、距新月的天数、月亮和太阳所在星座，以及下一个新月、上弦月、满月和下弦月的时间。

出生数据

natal_chart、annual_profection 以及 transits 和 synastry 的 natal / person_a / person_b 对象接受以下参数：

字段	类型	说明
date	"YYYY-MM-DD"	必填。本地日历日期。年份范围为 1800–2200。
time	"HH:MM"	本地时间，24 小时制。如果未知则省略：此时行星位置按当地正午计算，不提供上升点、天顶或宫位，并报告月亮当天的移动范围。
timezone	IANA 时区	例如 "Asia/Shanghai"、"America/New_York"。会应用历史夏令时（包括中国 1986–1991 年的夏令时）。
latitude, longitude	度	北纬和东经为正。计算上升点、天顶和宫位时必需。
city	字符串	可选，可从内置的约 110 个大城市表中快速选择（支持英文或中文名称）。明确提供的坐标和时区优先。没有地理编码服务：其他地点请传入坐标。
house_system	"placidus" | "whole_sign"	默认使用普拉西德宫制。在极圈内，若普拉西德宫制无法计算，则使用整宫制，输出也会注明。

其他参数：transits 接受 date、time、timezone、natal、max_orb；mercury_retrograde 接受 start_date、end_date、timezone；annual_profection 接受 age 或 on_date；moon_phase 接受 date、time、timezone。每个工具的 JSON 架构都包含各字段的说明。

输出

每次调用都会返回两个文本块和 structuredContent：

1. 一份面向模型的简明摘要，结尾会简短说明位置是计算得出的，解读应作为反思而非预测；
2. 相同数据的 JSON（也包含在 structuredContent 中）。

示例（natal_chart，1995-05-12 08:30，上海）：

Natal chart: 1995-05-12 08:30 Asia/Shanghai (UTC+08:00) · 31.23°N 121.47°E · Placidus houses
Sun 20°51′ Taurus (H11); Moon 11°41′ Libra (H4); Mercury 12°17′ Gemini (H12); Venus 24°00′ Aries (H10); Mars 24°13′ Leo (H2); Jupiter 13°00′ Sagittarius (H6) R; ...
ASC 12°04′ Cancer · MC 28°08′ Pisces
Aspects: Venus trine Mars 0.2° a; Moon trine Mercury 0.6° a; Mercury opposition Jupiter 0.7° a; ...
Balance: fire 20%, earth 20%, air 27%, water 33% → water; cardinal 40%, fixed 33%, mutable 27% → cardinal

约定

• 位置采用地心视角、视位置、回归黄道，并以日期为准。
• 同一星盘内的相位容许度：合相和对分相为 8°，四分相和三分相为 6°，六分相为 4°。两个星盘之间（合盘）：分别为 6°、5°、5°、3°。行运：所有相位使用相同容许度，默认 2°。
• 元素／模式平衡：太阳、月亮和上升点各计 2 分；水星至冥王星以及天顶各计 1 分。若得分相同，则依次以太阳、月亮、上升点的元素为准。
• 推运宫位从上升点起按整宫计数（出生时间未知时从太阳所在星座起算）；年主星采用传统守护星，若与现代共同守护星（冥王星、天王星、海王星）不同，则会注明。
• 影子期：前影期从水星首次到达其之后将顺行驻留的度数时开始；后影期在水星逆行后再次越过其逆行驻留的度数时结束。

不包括：小行星、月交点、莉莉丝、凯龙星、恒星黄道、普拉西德宫制和整宫制以外的宫位系统，以及解读文本。

Accuracy

The test suite compares the engine with Swiss Ephemeris (2.10.03, via pyswisseph) on 55 reference charts from 1900 to 2050 — northern and southern hemispheres, east and west longitudes, the equator, high latitudes up to and inside the Arctic Circle, historical daylight saving time, and unknown birth times. Every planet longitude, Ascendant, Midheaven and Placidus cusp is within 1′ of arc of the reference (largest gaps: planets 0.34′, Ascendant/Midheaven 0.20′, cusps 0.21′), and every UTC conversion matches. The angles use the true obliquity of the ecliptic (nutation included), as Swiss Ephemeris does. Only the reference numbers are included in this repository (tests/fixtures/reference-charts.json); no Swiss Ephemeris code is used or distributed.

Things to know:

• Time zones come from the IANA database built into Node.js. For dates before a region adopted standard time, the database uses local mean time; if your source used a different rule, pass the zone you mean (for example "Etc/GMT-8" for a fixed UTC+8).
• The Ascendant moves about a degree every four minutes: the chart is only as accurate as the birth time.
• The built-in city coordinates are city centres to about 0.01°.
• Retrograde stations are located to about a minute.

COSINE's methodology and accuracy notes: cosineastro.com/en/accuracy.

About interpretation

The positions are astronomy. What they mean is a tradition of interpretation, not a measurement. The server says so in every result and suggests that a model present readings as prompts for reflection rather than predictions or advice.

Development

npm install
npm test          # reference charts + every tool through an MCP client
npm run build
npm run smoke     # starts dist/index.js over stdio and calls each tool
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

Credits and license

MIT. The chart engine is ported from COSINE and uses astronomy-engine by Don Cross (MIT). Reference values for the tests were generated with Swiss Ephemeris by Astrodienst (used only to produce the numbers; not part of this package).

Made by COSINE — https://www.cosineastro.com · Free birth chart · Accuracy

---

繁體中文

cosine-astro-mcp 是一個 MCP 伺服器，提供西洋占星（回歸黃道）計算：本命盤、行運、合盤、水星逆行、年度小限、月相。

大型語言模型自己推算行星位置往往不準。這個伺服器改用 astronomy-engine 星曆在本機離線計算，回傳一段給模型讀的精簡文字摘要，以及完整的 JSON 資料。不需要 API 金鑰，不連網。

由 COSINE 余弦（cosineastro.com）製作，和網站使用同一套星盤引擎。

安裝

需要 Node.js 20 以上。

• Claude Code：claude mcp add cosine-astro -- npx -y cosine-astro-mcp
• Claude Desktop／Cursor：在設定檔的 mcpServers 加入 "cosine-astro": { "command": "npx", "args": ["-y", "cosine-astro-mcp"] }（完整範例見上方英文說明）

工具

工具	內容
natal_chart	本命盤：十顆行星的星座、度數、宮位、逆行；上升、天頂；十二宮頭（預設 Placidus，極圈內改用整宮制並註明）；主要相位與容許度、入相／出相；元素與模式的分布及主導。
transits	指定時刻（預設現在）的行星位置；若提供本命盤，列出行運行星對本命行星、上升、天頂的相位（預設容許度 2°）及所落本命宮位。
synastry	合盤：雙方行星（含上升）之間的相位、各自行星落入對方的宮位，以及簡單的相位統計（不是配對分數）。
mercury_retrograde	日期範圍內的水星逆行：前影期開始、停滯轉逆、停滯轉順、後影期結束（精確到約一分鐘），以及兩次停滯的度數。
annual_profection	依年齡或日期計算年度小限：小限宮位與星座（從上升星座以整宮計；不知出生時間則從太陽星座起算）、年主星及其本命位置、該小限年的起訖日期。
moon_phase	月相名稱、照亮比例、日月角距、月齡，以及下一次新月、上弦、滿月、下弦。

出生資料：date（YYYY-MM-DD，必填）、time（HH:MM，不知道就省略：不給上升、天頂與宮位）、timezone（IANA 時區，如 Asia/Taipei，自動套用歷史夏令時間）、latitude／longitude（北緯、東經為正），或用 city 從內建約 110 個大城市（中英文名皆可，繁簡皆可）中選取。不呼叫任何地理編碼服務；其他地點請直接給經緯度。

準確度

測試以 Swiss Ephemeris（2.10.03，pyswisseph）計算的 55 張參考星盤（1900–2050 年，涵蓋南北半球、東西經、赤道、高緯度與北極圈內、歷史夏令時間、出生時間不詳）比對：所有行星黃經、上升、天頂與 Placidus 宮頭誤差都在 1 角分以內（最大：行星 0.34′、上升／天頂 0.20′、宮頭 0.21′），UTC 換算全部一致。上升與天頂使用含章動的真黃赤交角，與 Swiss Ephemeris 相同。本專案只收錄參考數值，不含也不散布任何 Swiss Ephemeris 程式碼。準確度說明見 cosineastro.com/en/accuracy。

關於解讀

行星位置是天文計算；它們代表什麼，屬於占星的詮釋傳統，而非測量結果。每次回傳都附上提示：請把解讀當作自我反思的參考，而不是預言或建議。

授權

MIT。星盤引擎移植自 COSINE，使用 Don Cross 的 astronomy-engine（MIT）。

由 COSINE 製作 — https://www.cosineastro.com · 免費排本命盤