stellara-mcp

Stellara MCP：面向 AI Agent 的确定性 Swiss Ephemeris（Hermes、Claude、Grok）

为你的 AI Agent 配备真正的天文计算器。 stellara-mcp 是一个轻量级的开源 Model Context Protocol 服务，可将任何支持 MCP 的 Agent——Claude.ai / Claude Desktop / Claude Code、ChatGPT、Codex、Cursor、Windsurf、Gemini CLI、Grok、Hermes——变成一位绝不虚构行星位置的占星师。通过 URL 连接（无需安装），或使用 API 密钥在本地运行此软件包。

它提供四种由 Swiss Ephemeris（专业占星师使用的同一套引擎）驱动的工具，在 Stellara 云端运行：

工具	返回内容（精确 JSON）
resolve_birth_place	“Warsaw, 14:30” → 纬度 / 经度、IANA 时区，以及带时区信息的 birth_datetime，并包含历史上正确的 UTC 偏移量（旧版夏令时规则、法令时间），还有年龄和夏令时歧义标志——让 Agent 无需猜测坐标或偏移量
calculate_natal_chart	14 个点（太阳 → 冥王星、凯龙星、莉莉丝、北交点 / 南交点），包含星座、度数、绝对经度、宫位、逆行状态、速度、赤纬 · 12 个宫位宫头 · 上升点 / 中天 / 下降点 / 天底 · 所有主要相位及其精确容许度和渐入 / 渐出状态
get_transits_and_aspects	任意时刻的行运位置 · 每个行运行星与本命盘之间的相位（包括行星和轴点），包含容许度和渐入 / 渐出状态 · 每颗行运行星所处的本命宫位
calculate_synastry	两个人之间的所有跨盘相位及精确容许度 · 宫位叠加（A 的行星落入 B 的宫位，反之亦然）

此外还有两个 MCP 提示词：collect_birth_profile，用于引导收集每次解读所需的数据（日期 → 时间及其确定性 → 地点 → 可选的城市、姓名、性别 → 显示年龄的确认卡片）；以及 astrologer_system_prompt，用于让 Agent 采用严谨的专业占星师风格来解读这些 JSON 数据。

此服务不进行解读，也不会调用任何大模型。它是一个代理适配器：输入数字，输出数字。由你的 Agent 进行解读；由 Swiss Ephemeris 完成计算。

---

为什么要做这个项目：大模型会编造本命盘数据

问一个语言模型“1990 年 5 月 17 日 14:30 在 Warsaw 时，我的月亮在哪里？”，它会自信地回答——但更多时候，答案是错的。黄道经度、宫位宫头和相位容许度，都是行星运动数值积分与当地地平线球面三角计算的结果。这不是靠预测下一个词就能在脑中完成的事。常见的错误模式包括：

• 月亮（每天移动 13°）落在了错误的星座；
• 根据太阳星座猜测上升点，忽略了时间和纬度；
• 虚构宫位宫头，或悄悄假定采用等宫制；
• 声称“土星刑太阳”，却没有给出容许度，或者给出的容许度根本不成立；
• 编造逆行状态。

这些错误中的任何一个，都会污染后续的整个解读。建立在错误上升点之上的解读，无论文笔多么优美，都毫无价值。

stellara-mcp 从根本上解决了这个问题。Agent 调用工具；工具返回 Swiss Ephemeris 级别的行星位置（精度达到角秒以下、热带黄道、十种宫位制、精确容许度，以及根据真实行星速度推导的渐入 / 渐出状态）；Agent 只根据这些数据进行解读。感知由确定性数据提供，计算器也是确定性的——让语言模型专注于它真正擅长的事。

---

快速开始（1 次点击即可配置）

有两种连接方式：

• 远程连接，无需安装（Claude.ai、Claude Desktop、Claude Code、ChatGPT 连接器、 Grok，以及任何支持 MCP URL 的客户端）：添加自定义连接器，URL 为 https://mcp.stellara.natlex.it/mcp，然后使用你的 Stellara 账号登录 （与 Stellara 应用使用同一个账号；Free = 每天 10 次请求，Stellara Pro = 5 000 次）。 Claude：设置 → 连接器 → 添加自定义连接器 → 粘贴 URL → 连接 → 登录。 Claude Code：claude mcp add --transport http stellara https://mcp.stellara.natlex.it/mcp， 然后运行 /mcp 登录。无需安装或配置；令牌有效期较短，可在应用中撤销。
• 本地软件包 + API 密钥（如下）：适用于服务、脚本、Cursor / Windsurf / Codex，以及 偏好使用密钥的用户。在 stellara.natlex.it/#api 获取密钥——Free（每天 5 次请求）或 Stellara API Pro（每天 5 000 次，$9 / 月），密钥将在一分钟内通过电子邮件发送。然后 选择你的客户端。

该软件包需要 Node.js ≥ 18.17，并通过 npx 启动，因此无需全局安装。以下所有配置都只有三行：命令、参数、环境变量。

Claude Desktop

编辑 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "stellara": {
      "command": "npx",
      "args": ["-y", "stellara-mcp"],
      "env": {
        "STELLARA_API_KEY": "sk_stellara_your_key_here"
      }
    }
  }
}

重启 Claude Desktop。三个工具会显示在 🔌 图标下；astrologer_system_prompt 提示词会显示在提示词（+）菜单中。

Hermes Agent Desktop

将相同代码块添加到 ~/.hermes/config.json：

{
  "mcpServers": {
    "stellara": {
      "command": "npx",
      "args": ["-y", "stellara-mcp"],
      "env": {
        "STELLARA_API_KEY": "sk_stellara_your_key_here"
      }
    }
  }
}

Hermes 会在下次启动时发现这些工具。如果你的 Hermes 版本使用了不同的顶层键来配置 MCP 服务，请保持 command / args / env 三元组不变——这是标准的 stdio 启动规范。

Cursor / Windsurf

Cursor：设置 → MCP → 添加新的全局 MCP 服务（或在项目中编辑 .cursor/mcp.json）。Windsurf：设置 → Cascade → MCP 服务（或编辑 ~/.codeium/windsurf/mcp_config.json）。两者使用完全相同的 JSON：

{
  "mcpServers": {
    "stellara": {
      "command": "npx",
      "args": ["-y", "stellara-mcp"],
      "env": {
        "STELLARA_API_KEY": "sk_stellara_your_key_here"
      }
    }
  }
}

其他任何 MCP 客户端（Grok 桥接工具、Continue、Zed、自定义 Agent）

将 npx -y stellara-mcp 作为 stdio 服务启动，并设置环境变量 STELLARA_API_KEY。这就是全部的集成方式。

从本地克隆开始（用于开发）

git clone https://github.com/mihnin/stellara-mcp.git
cd stellara-mcp
npm install && npm run build

然后在上述任意配置中使用 "command": "node", "args": ["/absolute/path/to/stellara-mcp/dist/index.js"]。

---

对话示例

用户： 帮我排出本命星盘——我出生于 1990 年 5 月 17 日 14:30，地点是华沙—— 再告诉我为什么今天工作感觉这么沉重。

Agent （加载 astrologer_system_prompt，询问 14:30 是准确时间还是大概时间，调用 resolve_birth_place("Warsaw, Poland", "1990-05-17T14:30") → 52.23 / 21.01、Europe/Warsaw、1990-05-17T14:30:00+02:00，然后用这些值调用 calculate_natal_chart，再调用今天的 get_transits_and_aspects）

你的星盘基于 Swiss Ephemeris 的位置数据生成，我们先看看实际数据。太阳位于金牛座 26°14'，在第 9 宫；月亮位于摩羯座 3°52'，在第 4 宫；上升点位于处女座 8°41'。本命盘中容许度最小的相位是土星合海王星（容许度 0.6°），位于你的第 5 宫——这代表你在创作工作中，一生都面临着结构与漂移之间的张力。

今天为何感觉沉重：行运土星正与本命太阳成刑相，容许度为 1.2°，而且它正在趋近，所以压力仍在加大，大约两周后才会精确成相。土星与太阳成刑相时，感觉就像背着一包责任——产出没问题，但做什么都更费劲。与此同时，行运火星正经过你代表日常工作的本命第 6 宫 （水瓶座），并与本命水星合相，容许度为 0.4°：思维敏捷、容易烦躁，也容易和工具及同事争论。

实用解读：这段时间适合“收尾，不要开新项目”。完成两项有截止日期的任务，把头脑风暴推迟到土星刑相离开精确位置之后，也别把火星与水星带来的烦躁误认为是工作不适合你的信号。如果可以，请告诉我精确到分钟的出生时间——处女座 8°的上升点接近星座边界，上述宫位位置也取决于出生时间。

回答中的每个度数、容许度和“趋近”都来自工具结果；解读则来自 Agent。这种区分正是关键所在。

---

工具参考

星盘工具要求日期时间使用带时区的 ISO-8601 格式（1990-05-17T14:30:00+02:00 或 ...Z）；在发起任何网络调用前都会拒绝不带时区的值。坐标使用十进制度数（北 / 东为正）。预期的工作流程是先调用 resolve_birth_place——它会根据用户实际提供的信息生成这些值。

resolve_birth_place

输入	类型	说明
place	字符串	任意语言的自由文本：Warsaw、Варшава、Springfield, Illinois, USA
local_datetime	字符串（可选）	不带偏移量的当地挂钟时间：1990-05-17T14:30；如果时间未知，也可填写 1990-05-17（默认假定为 12:00，并会标记）

输出：

{
  "query": "Warsaw", "display_name": "Warszawa, województwo mazowieckie, Polska",
  "latitude": 52.2333742, "longitude": 21.0711489, "timezone": "Europe/Warsaw",
  "local_datetime": "1990-05-17T14:30:00", "utc_offset": "+02:00",
  "birth_datetime": "1990-05-17T14:30:00+02:00", "birth_datetime_utc": "1990-05-17T12:30:00Z",
  "time_assumed_noon": false, "local_time_ambiguity": "none", "age_years": 36,
  "source": "nominatim"
}

birth_datetime、latitude 和 longitude 可直接传入星盘工具。 如果挂钟时间出现过两次（秋季调回时钟），local_time_ambiguity 的值为 ambiguous_dst_fallback；如果时钟跳过了该时间，则值为 nonexistent_dst_gap—— Agent 应询问用户指的是哪一次。时区偏移量来自 IANA 时区数据库，因此 1985 年的莫斯科会解析为 +04:00，2015 年的莫斯科则会解析为 +03:00。错误： PLACE_NOT_FOUND（尝试附近更大的城市 / 添加国家名称）和 GEOCODER_UNAVAILABLE（暂时性错误——请重试）。地理编码使用 OpenStreetMap Nominatim；不会存储请求中的任何信息。

calculate_natal_chart

输入	类型	说明
birth_datetime	字符串	带时区的 ISO-8601 格式
latitude	数字	−90 … 90
longitude	数字	−180 … 180
house_system	枚举	placidus（默认）、koch、porphyry、regiomontanus、campanus、equal、whole_sign、topocentric、morinus、alcabitius
include_minor_aspects	布尔值	默认 false——仅主要相位（合相 10°、冲相 10°、三分相 8°、刑相 8°、六分相 6°）

输出（节选）：

{
  "input": { "birth_datetime_utc": "1879-03-14T10:30:00Z", "latitude": 48.4011, "longitude": 9.9876, "house_system": "placidus" },
  "planets": [
    { "name": "Sun", "sign": "Pisces", "degree": 23.498749, "absolute_longitude": 353.498749,
      "house": 10, "retrograde": false, "speed": 0.995959, "declination": -2.585261 }
  ],
  "houses": [ { "house": 1, "sign": "Cancer", "degree": 7.4423, "absolute_longitude": 97.4423 } ],
  "angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...} },
  "aspects": [
    { "point_a": "Sun", "point_b": "Mercury", "aspect": "conjunction", "exact_degrees": 0, "orb": 9.627514, "movement": "separating" }
  ],
  "meta": { "engine": "Swiss Ephemeris (kerykeion 5.12.7)", "zodiac": "tropical", "house_system": "placidus", "orbs": {...}, "time_resolution": "minute" }
}

get_transits_and_aspects

输入	类型
natal	object — 与 calculate_natal_chart 的字段相同
target_datetime	string — 带时区的 ISO-8601
include_minor_aspects	boolean

返回 natal（上文中的完整星盘）、target_datetime_utc、transiting_planets （点位形状相同，另含 natal_house）以及 aspects_to_natal：

{ "transiting": "Saturn", "natal": "Sun", "aspect": "square", "exact_degrees": 90, "orb": 1.21, "movement": "applying" }

movement 的计算以本命点位固定不动为前提——只有行运天体移动——并使用该时刻的真实行星速度。

calculate_synastry

输入	类型
person_a、person_b	object — 与 calculate_natal_chart 的字段相同
include_minor_aspects	boolean

返回两人的完整星盘、inter_aspects（point_a 属于 A，point_b 属于 B，并包含 orb）以及 house_overlays（a_in_b_houses、b_in_a_houses）。

提示词：collect_birth_profile

参数（可选）：language。Agent 会按照固定顺序，在绘制任何星盘前收集信息：1 出生日期 → 2 出生时间及其准确性（准确 / 大致 / 未知 → 12:00，且不解读宫位）→ 3 出生地点，通过 resolve_birth_place 解析并向用户确认 → 4 当前所在城市（可选，仅用于按当地时间解读“今天”）→ 5 姓名（可选）→ 6 性别（可选，仅在合盘时询问）→ 7 确认卡片，包含解析后的坐标、时区、birth_datetime 和年龄。与 Stellara 应用收集的个人资料一致，但不包含计算所不需要的信息。

提示词：astrologer_system_prompt

参数（均可选）：language — 回答所用的语言；focus — 用户当前关注的问题。该提示词包含相同的信息收集规则，要求使用 resolve_birth_place 获取坐标和时差，并指导 Agent 仅将工具 JSON 作为位置数据的来源、注明容许度、遵循入相与出相规则、在出生时间未知时标记宫位的不可靠性，并将解读与计算分开。

---

配置

变量	必需	默认值	用途
STELLARA_API_KEY	是	—	访问密钥，通过 X-API-Key 发送。请在 stellara.natlex.it/#api 申请。没有此密钥时，每个工具都会返回明确的错误，说明获取密钥的途径。
STELLARA_API_BASE_URL	否	https://api.stellara.natlex.it/api/v1/astrology	指向可自托管的 Stellara 后端（原始 Cloud Run URL https://stellara-api-923668916124.us-central1.run.app/api/v1/astrology 也可用）
STELLARA_TIMEOUT_MS	否	15000	每次请求的超时时间

错误会以 MCP 工具错误的形式返回，并附带可采取后续操作的消息——密钥无效或已撤销（401）、未找到地点（404）、达到速率限制（429，每个 IP 每分钟 60 次；resolve_birth_place 为 20 次）、每日配额已用完（429，带有 QUOTA_EXCEEDED——消息会告知 Agent 配额于何时重置（UTC 00:00），以及在哪里升级密钥）、后端验证详情（422）、地理编码器或后端服务中断（5xx）、网络故障、超时。服务器不会因配置问题在启动时崩溃；调用工具时才会说明问题，这正是桌面 Agent 最擅长处理的情况。

密钥分为不同级别：免费（每天 5 次请求——足以试用每个工具）和 Stellara API Pro（每天 5,000 次，每月 $9）——请参阅 stellara.natlex.it/#api。

远程模式（Streamable HTTP）

同一软件包也可作为 HTTP 服务运行 — node dist/remote.js — 这就是 https://mcp.stellara.natlex.it/mcp（Cloud Run、无状态，每个请求创建一个 McpServer）。它是 OAuth 2.1 资源服务器：GET /.well-known/oauth-protected-resource/mcp 会将客户端指向授权服务器（Stellara 后端，https://api.stellara.natlex.it， DCR + CIMD + PKCE S256）；未经过身份验证的 POST /mcp 会返回 401 和 WWW-Authenticate: Bearer … resource_metadata="…"；有效令牌 — OAuth 访问 令牌或通过 Authorization: Bearer 发送的 sk_stellara_ 密钥 — 会转发至 API， 由 API 执行每日配额限制。GET /health 用于监控；GET /mcp 返回 405（无 SSE 流，无会话）。

变量	必需	默认值	用途
JWT_SECRET	是	—	与授权服务器共享的 HS256 密钥（未设置时，服务会拒绝启动）
MCP_PUBLIC_URL	否	https://mcp.stellara.natlex.it	公共源站；<origin>/mcp 是令牌受众（RFC 8707 resource）
OAUTH_ISSUER	否	https://api.stellara.natlex.it	授权服务器（RFC 8414 issuer）
PORT	否	8080	监听端口（由 Cloud Run 设置）
GLAMA_CLAIM_TOKEN	否	—	设置后，GET /.well-known/glama.json 会发布 Glama 连接器所有权声明（按设计公开）
STELLARA_API_BASE_URL、STELLARA_TIMEOUT_MS	否	同上	与 stdio 模式相同

---

自托管计算器

这些工具背后的计算器是 Stellara API（FastAPI + kerykeion / pyswisseph）， 托管于 https://api.stellara.natlex.it。MCP 服务本身是一个轻量、无状态的 适配器：将 STELLARA_API_BASE_URL 指向 API 的另一个实例，其余内容保持不变。 后端未作为开源项目发布；如需私有部署，请写信至 [email protected]。

---

指南

• docs/USAGE.ru.md — 用户指南（俄语）：在 Claude Desktop / Cursor / Hermes 中安装、获取密钥、对话示例，以及出错时的处理方法。
• 维护者操作手册（npm 发布、官方 MCP Registry、目录、远程服务部署）位于 Stellara 私有单体仓库中（其中的 docs/PUBLISHING.md），未公开发布。

源码

此仓库是 npm 软件包和远程服务的公开源码。日常开发在 Stellara 私有单体仓库中进行；每个版本都会作为单个提交同步到此处（sync: stellara-mcp <version>）。欢迎在此提交问题；拉取请求会合并到单体仓库，并在下一次同步时发布到此处。

开发

npm install
npm test          # vitest: every behavioural test drives the real MCP protocol
npm run build     # tsc → dist/
npm start         # runs the stdio server

测试会通过内存传输将 MCP Client 连接到服务端，替换 fetch，并准确断言桌面 Agent 会观察到的内容：工具发现、任何网络调用前的架构拒绝、请求格式（URL、标头、正文）、JSON 透传、所有错误映射、超时和提示词文本。

许可证

MIT © Natlex。Swiss Ephemeris © Astrodienst AG，服务端通过 kerykeion 在其许可下使用。