mcp-ephemeris

@cosmosos/mcp-ephemeris

真实天空，为你的 AI 而来。 一个 MCP 服务 ，为任何助手（Claude、Cursor、agents）提供计算得出的行星 位置——绝非猜测，由 Swiss Ephemeris 引擎驱动，并经过 JPL Horizons（NASA）验证，精度优于 1 角秒。

基本原则：大模型绝不进行计算。 此服务是历书引擎的门面。 模型负责解读；天空是事实。

（法语版本：https://llmastro.com/notre-moteur）

快速开始（Claude Desktop）

打开设置 → 开发者 → 编辑配置，然后添加：

{
  "mcpServers": {
    "llmastro": {
      "command": "npx",
      "args": ["-y", "@cosmosos/mcp-ephemeris"]
    }
  }
}

完全退出 Claude Desktop（包括系统托盘），然后重新启动。接着询问： “今天的月相是什么？”——Claude 会调用此服务，并根据 实际计算得出的位置作答。

Cursor / Windsurf / 其他客户端：在客户端的 MCP 配置中添加相同的 llmastro 条目 （command: npx、args: ["-y", "@cosmosos/mcp-ephemeris"]）。

提供的工具

19 个工具，全部由同一个服务端计算引擎提供支持。

位置与天空

工具	输入	输出
get_planet_positions	datetime（ISO UTC）	所有天体的黄道位置（星座、度数、逆行状态）
get_moon_phase	datetime（ISO UTC）	月相、照明百分比、描述
get_current_sky	latitude、longitude	某地点此刻的天空（当前行运）
get_aspects	datetime（ISO UTC）	天体之间主要与次要相位的网格

出生星盘与关系

工具	输入	输出
get_natal_chart	出生信息 + zodiac（热带黄道 / 恒星黄道）、houseSystem（7 种宫位制）	完整星盘：宫位、相位、ASC/MC、月相、赫尔墨斯点
get_transits	出生信息 + 可选的 datetime	行运→出生星盘相位，按容许度排序
get_synastry	两组出生信息	星盘间相位 + 和谐 / 紧张概述
get_composite_chart	两组出生信息	中点组合盘
get_secondary_progressions	出生信息 + targetDate	推运位置（“一日代表一年”）
get_solar_return	出生信息 + year（+ 可选地点）	太阳回归的精确时刻 + 星盘
get_lunar_return	出生信息 + 可选的 after	下一次月亮回归的精确时刻 + 星盘

天文事件

工具	输入	输出
get_ingresses	body、start、end	星座变更日期（稳健处理逆行）
get_retrograde_windows	body、start、end	时间范围内逆行 / 顺行停滞点
get_eclipse_details	datetime、kind	已知日食 / 月食的食分、遮蔽率、沙罗周期 (swisseph)
get_next_eclipse	from、kind、可选的 backward	下一次 / 上一次日食或月食：最大食、类型、接触时刻 (swisseph)

占星地理学、数字命理、权威信息

工具	输入	输出
get_astrocartography	datetime（ISO UTC）	行星 MC/IC 线 + 副线（交点）
get_life_path	date（YYYY-MM-DD）	生命灵数
get_engine_diagnostic	—	当前使用的引擎、原生插件加载状态、实际精度
validate_against_horizons	datetime、可选的 bodies	我们的位置与 JPL Horizons（NASA）之间的角秒差值——需要网络连接

（swisseph） = 需要原生 Swiss Ephemeris 插件；使用 AstraCore 备用方案时返回 null。

精度

使用 Swiss Ephemeris 时，位置与 全球参考标准 JPL Horizons（NASA） 的误差小于 1 角秒（测量于 2026-07-19）：

天体	与 NASA 的差异
太阳	0.2″
月亮	1.5″
木星	0.1″
冥王星	0.4″

使用 validate_against_horizons 工具自行验证。

两种引擎

计算由 ASTRO_ENGINE 变量路由：

• swisseph（默认）——Swiss Ephemeris，原生插件，精度达角秒以下。只要环境中具备 C++ 构建工具链，就会自动编译（Linux、macOS 和大多数服务器）。
• astracore——内部开发的纯 TypeScript 引擎（VSOP/Meeus），无原生二进制文件。当 swisseph 无法编译时会自动回退到此引擎（Windows 上较为常见）。太阳和月亮的位置仍然准确；外行星的位置误差会达到几角分。

强制指定引擎：ASTRO_ENGINE=swisseph 或 ASTRO_ENGINE=astracore。

隐私

该服务在你的计算机上运行：你的出生数据不会发送到任何地方。只有 validate_against_horizons 会发出出站请求（调用 NASA 的公共 API）。

要求

• Node.js ≥ 20。
• 如需最高精度（swisseph）：计算机上需要有 C++ 构建工具链（python3、make、编译器）。否则会自动回退到 astracore，无需配置。

关于

由 Llmastro 的占星引擎提供支持。了解更多关于精度和架构的信息：https://llmastro.com/notre-moteur。

许可证

可免费用于非商业用途（个人、研究、教育、非营利组织）——遵循 PolyForm Noncommercial 1.0.0 许可证。

商业／专业用途：需要付费许可证。 如需获取许可证，请通过 https://llmastro.com/contact 联系 KAIROSAST LTD。

注意：可选依赖项 swisseph（Swiss Ephemeris，Astrodienst）有自己的许可证（AGPL 或 Swiss Ephemeris 商业许可证），不受本许可证涵盖。专业用途必须另行遵守其许可证。

开发

此代码仓库内容齐全：历书引擎以源代码形式包含在 vendor/ephemeris/ 中，构建过程通过 tsup 将其内联到 dist/ 中。

pnpm install          # or npm install
pnpm build            # bundles dist/index.js (engine inlined)
pnpm start            # runs the MCP server (stdio) locally

• 默认引擎：如果原生插件能够编译，则使用 swisseph（精度达角秒以下）；否则自动回退到 astracore（纯 TypeScript，无二进制文件）。通过 ASTRO_ENGINE=swisseph|astracore 强制指定。
• 内置引擎是 @astro-platform/ephemeris（Llmastro）的快照，需手动重新同步。