GetBirthChart MCP

@getbirthchart/mcp

GetBirthChart 占星计算的官方 MCP 服务 0.2.0。它通过公开的 GetBirthChart API，为兼容 MCP 的 AI 客户端提供结构化计算结果；其中不包含也不会重新实现占星引擎。

要求

• Node.js 20 或更高版本
• GetBirthChart 开发者 API 密钥

在 getbirthchart.com/developers 创建密钥。请妥善保管，不要提交包含真实密钥的 MCP 主机配置。

快速开始

该软件包通过 MCP stdio 运行，可使用 npx 启动：

{
  "mcpServers": {
    "getbirthchart": {
      "command": "npx",
      "args": ["-y", "@getbirthchart/[email protected]"],
      "env": {
        "GETBIRTHCHART_API_KEY": "gbc_live_your_key_here"
      }
    }
  }
}

对于支持 MCP stdio 服务的主机，这是标准的命令配置。确切的配置文件位置或 UI 位置，请参阅客户端的最新文档；本仓库已通过官方 MCP TypeScript 客户端进行协议测试，未使用特定供应商的客户端。

环境变量

变量	必填	说明
GETBIRTHCHART_API_KEY	是	服务端开发者 API 密钥。
GETBIRTHCHART_API_BASE_URL	否	用于开发／测试的 HTTPS API 基础 URL 覆盖值。仅 localhost 接受 HTTP。

密钥会在启动时读取，不会作为工具参数接受，也不会写入 stdout、日志、资源或工具结果。

可用工具

所有工具均为只读，并返回结构化的计算事实。输入使用严格字段：date、可选的 time 和 place、必需的 latitude、longitude 和 timezone，以及可选的 unknown_time 和下文所述的计算设置。

工具	输入	输出	是否需要精确时间？	未知时间行为
calculate_birth_chart	birthData	映射后的本命星盘	否	省略上升点和宫位；保留不确定性。
get_planet_positions	birthData	行星落点	否	保留星盘的不确定性。
get_big_three	birthData	太阳、月亮和可选的上升点	否	不猜测上升点。
get_moon_sign	birthData	月亮星座及不确定性	否	如果后端无法确定唯一星座，则返回模糊结果。
get_rising_sign	birthData	上升星座	是	返回 birth_time_required。
calculate_aspects	birthData	本命相位	否	仅返回由后端提供的事实。
calculate_synastry	person_a、person_b、关系字段	合盘相位和摘要	每人分别判断	保留每个人因时间未知而受到的限制。

当前公开 API 不会对 place 进行地理编码；即使包含地点标签，也必须提供纬度、经度和 IANA 时区。MCP 服务绝不会编造出生时间。对于未知时间的评估，后端可能会使用当地午夜作为标注的计算基准，但绝不会将该基准说成此人的出生时间，也绝不会猜测宫位、上升点或存在歧义的月亮星座。

输入示例：

{
  "date": "1990-01-15",
  "time": "12:00",
  "place": "New York, NY",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

时间未知：

{
  "date": "1990-01-15",
  "unknown_time": true,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

计算选项

本命工具接受 gbc-astro 1.13.0 暴露的核心选项 house_system、node_type、aspect_preset、custom_aspect_rules、additional_points、fold、zodiac 和 ayanamsa。若要使用兼容旧版的默认设置，请省略这些选项：Tropical、Placidus、True Node、Standard aspects、开启 Chiron、关闭 Lilith。恒星黄道计算需要指定 ayanamsa 名称；Lahiri 是推荐的产品选项。自定义相位需要设置 custom_aspect_rules，每条规则使用 type、exact_angle 和 orb。

实现暴露了核心中与产品相关的宫位系统（placidus、whole_sign、equal），以及已注册的引擎系统、Mean Node、Standard/Extended/Custom 本命相位、Mean/True Lilith、Vertex 和 Part of Fortune 请求，以及具名的恒星黄道 ayanamsa。MCP 合约不会增加计算逻辑或解读。Composite 和 Davison 是核心/SDK 操作，但在此版本中不是 MCP 工具。

合盘接受关系级别的 node_type，以便两张星盘使用同一种交点约定；也接受可选的 relationship_type、topic 和 target_instant。服务会保留响应元数据和新增的 schema 1.x 字段。本命 HTTP 响应可以不包含 calculationHash；这是有效的，且从不要求必须包含。服务会原样保留返回的 v2: 计算哈希，不会更改或截断。核心兼容版本为本命 schema 1.9.0 和合盘 schema 1.5.0。

资源

• getbirthchart://methodology — 计算约定和出生时间未知时的边界。
• getbirthchart://data-sources — 星历、时区和地点输入的数据来源信息。
• getbirthchart://engine-info — 提供方和公共 API 元数据。

权威网页参考：方法论和数据来源。

错误

工具失败时会返回结构化的 error 数据，其中包含安全、机器可读的 code、消息、retryable，以及可选的 retry_after。常见代码包括 validation_error、authentication_required、birth_time_required、location_not_found、ambiguous_location、rate_limit_exceeded、timeout 和 internal_error。

故障排除

• **缺少 API 密钥：**在 MCP 主机的服务环境中设置 GETBIRTHCHART_API_KEY；它不是工具参数。
• **身份验证或速率限制错误：**如果存在，请使用结构化错误中的 code 和 retry_after。不要在工具调用或客户端日志中填写密钥。
• **出生时间未知时的验证：**当 unknown_time 为 true 时，请省略 time；服务不会擅自替换为中午或臆造上升星座。
• **地点验证：**请提供数字格式的 WGS84 latitude、longitude 和 IANA timezone；place 仅为标签，不会在此处进行地理编码。
• **本地开发：**仅在使用 HTTPS 或 localhost 上的 HTTP 时设置 GETBIRTHCHART_API_BASE_URL。切勿将生产密钥发送到不可信主机。

隐私与安全

出生数据仅会发送至配置的公共 API，用于执行所请求的计算。本软件包不会持久化、缓存或记录出生输入，也不包含分析或遥测功能。可选的基础 URL 覆盖设置会改变信任边界；切勿将生产密钥发送到不可信主机。

请通过 SECURITY.md 中的流程私下报告安全问题。请勿在错误报告中包含 API 密钥。

开发

npm install
npm run lint
npm run typecheck
npm test
npm run build

测试使用模拟客户端，不会调用生产 API。若要在本地运行构建后的服务，请设置 GETBIRTHCHART_API_KEY 并执行 node dist/cli.js；常规协议流量会写入 stdout，启动失败信息则写入 stderr。

链接

• 开发者中心
• GitHub 仓库
• Core 1.13.0 GitHub 发行版
• PyPI 上的 Core 1.13.0
• Core OpenAPI 源码
• 概念 DOI · 版本 DOI
• npm 软件包

MCP Registry 元数据

Registry 元数据已在 server.json 中准备就绪，服务名称为 io.github.getbirthchart-com/getbirthchart-mcp。请先发布 npm 软件包，然后使用官方 mcp-publisher 工具进行身份验证并发布元数据。Registry 提交不会纳入软件包构建或 CI 工作流。