astral-mcp

Astral MCP

为 AI Agent 提供真正的占星功能 — 本命盘、行运、合盘与月相。
在本地计算，由两个独立星历交叉核验。无需 API 密钥，无需账户。

⚡ 零配置安装。 将其接入 Claude Desktop / Cursor / Hermes，即可立即调用 — 无需 API 密钥、无需 OAuth、无需账户： npx -y astral-mcp

一个本地优先的 MCP 服务，可将出生数据转换为完整且经过精度审计的占星解读，供 AI Agent 使用。 无状态且以计算为主——不会存储任何内容，也不涉及凭据；除可选的地理编码外，所有工具都可完全离线运行。

Astral MCP 是 Delx 专注于占星的产品。请参阅 Delx 平台图，了解它与独立的 Protocol、Security、Wellness 和 Commerce 产品的边界。

由 David Mosiah 构建。占星引擎移植自 Alkhemia 应用。

刚接触这种协议模式？请阅读 什么是占星 MCP 服务？，了解确定性星盘计算与模型解读之间的区分、推荐的 Agent 工作流，以及精度与隐私边界。

准备好计算星盘了吗？请参阅 如何使用 MCP 生成本命盘，了解准确的出生地、时区、出生时间未知时的处理方式、载荷以及精度审计工作流。

需要处理敏感输入？请阅读 如何在占星 Agent 工作流中保护出生数据，了解载荷最小化、本地计算、可选的 OpenStreetMap 边界，以及 privacy_mode=summary 的局限。

为什么要构建它

大多数占星库都是脆弱的单引擎封装，而大多数“占星 API”都需要密钥和订阅。Agent 需要可信且可即时调用的工具。Astral MCP 在两方面有所不同：

1. 开箱即用。 运行 npx -y astral-mcp，即可调用星盘——无需 OAuth、无需账户，也无需安装出生地数据库。
2. 自我校验。 每张本命盘都先用一个星历计算，再通过第二个星历逐个行星独立重新推导。如果结果超出严格的容差范围，星盘会被标记为 review，而不是悄悄返回错误的位置。

60 秒完成设置

将其添加到你的 MCP 客户端（Claude Desktop、Cursor、Hermes 等）：

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

设置就这么简单，无需身份验证。

也可以直接运行：

npx -y astral-mcp                      # stdio (default)
ASTRAL_MCP_TRANSPORT=http npx -y astral-mcp   # streamable HTTP on 127.0.0.1:3000

连接前先看看效果

调用 astral_demo，即可查看完整的示例星盘（格林威治、正午、Y2K），其中包含精度审计——无需输入、无需联网，也无需身份验证。它会展示确切的载荷格式，让你在发送真实出生数据前先了解其结构。

用你的 Agent 试试看

“我的本命星盘是什么？我出生于 1989 年 2 月 23 日 14:30，地点是巴西福塔莱萨。”

Agent 会调用 astral_search_birthplace，将福塔莱萨解析为纬度／经度／时区，然后调用 astral_compute_natal_chart。

“这周有什么重要行运会影响我的星盘吗？” → astral_current_transits “我们的匹配度如何？”（两人的出生数据） → astral_synastry “今天月亮处于什么阶段？” → astral_moon_phase

精度

Astral MCP 会为每张本命星盘提供精度审计。主引擎（circular-natal-horoscope-js）负责计算星盘；验证器（astronomy-engine）则独立重新推导每颗行星的黄经。只有当每颗行星的结果都在容差范围内一致，且落入相同星座时，星盘才会标记为 verified。

在内置的准确度测试集中，涵盖了 1945—2010 年、横跨六个时区的星盘，跨引擎的最大误差小于 0.01°。你可以自行运行：

npm run test:accuracy

数据可用性

能力	支持情况
行星（太阳…冥王星）、上升点、中天／天底	✅
宫位（placidus、koch、campanus、regiomontanus、topocentric、equal-house、whole-sign）	✅
主要相位，含容许度、强度、入相／出相	✅
星盘特征（主导元素／模式、格局、群星、角宫行星）	✅
逆行 · 时区／夏令时处理	✅
行运（当前 + 即将发生）· 月相	✅
合盘（双星盘比较，带评分）	✅
回归黄道与恒星黄道	✅
月交点、凯龙星、小行星、恒星	⏳ 计划支持
次要相位	⏳ 计划支持
解读文本	❌ 有意不提供 — astral-mcp 返回结构化数据；由你的模型撰写解读

工具

• astral_compute_natal_chart — 完整本命星盘，默认进行精度审计
• astral_current_transits — 对星盘进行当前及即将发生的行运分析，并提供月相
• astral_synastry — 比较两张星盘（和谐度／化学反应／沟通／成长）
• astral_moon_phase — 查询任意日期的月相、星座和照明比例
• astral_search_birthplace — 将地点转换为纬度／经度／时区
• astral_demo — 完整示例星盘，无需输入
• astral_capabilities — 查看此服务支持和不支持的功能
• astral_data_inventory — 数据领域及建议的首次调用
• astral_agent_manifest — 面向 Agent 的安装和使用规则
• astral_connection_status — 通过示例星盘和双引擎审计进行运行状况检查

三个星盘工具（astral_compute_natal_chart、astral_current_transits、astral_synastry）都接受一个 privacy_mode 参数——这是与 response_format 分开的载荷详略级别：

• full（默认）— 完整载荷，包括逐颗行星的精度审计
• structured — 保留相同结构，但省略冗余或可推导字段
• summary — 仅包含关键信息（发光体 + 上升点、星盘特征、主要相位）

完整的格林威治本命星盘载荷约为 6.9 KB；summary 约为 1.2 KB（缩小约 80%），因此，只需快速了解情况的 Agent 可以请求较少的数据，从而减少 token 消耗。

准确解读须知

• 传入出生地的时区，而不是调用者所在地的时区。astral_search_birthplace 会返回该时区。
• birth_time 为可选参数。若未提供，则默认使用正午：行星星座仍然准确，但上升点和宫位不可靠。

隐私与安全

Astral MCP 不存储任何内容，也不保留任何机密信息。唯一可选的网络调用是 astral_search_birthplace（OpenStreetMap），它只会发送你传入的地点名称字符串。请参阅 SECURITY.md。

参与贡献

src/engine/ 中的计算核心移植自 Alkhemia——请保持其独立于框架。请参阅 AGENTS.md，了解开发规则和测试门槛（npm test）。

许可证

MIT——请参阅 LICENSE。

HTTP（v2 无状态）

默认使用 stdio。可选的 Streamable HTTP——无会话 ID，JSON 响应，仅限环回连接：

npx -y astral-mcp --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

环境变量：ASTRAL_MCP_HOST、ASTRAL_MCP_PORT、ASTRAL_MCP_TRANSPORT=http。

Skill 还是 MCP

npx -y astral-mcp call astral_connection_status --json '{}'