Céu Natal

Céu Natal

使用瑞士星历计算星盘，供 AI 助手解读的 MCP 服务。

英文版。 Céu Natal 是一个开源的模型上下文协议服务，可使用瑞士星历计算出生星盘、合盘、行运、推运以及太阳／月亮回归，并以葡萄牙语作答。免费公共端点运行于 https://astrologia-mcp.gustavocancado.com.br/mcp/（无需注册）。采用 AGPL-3.0 许可。 Claude、ChatGPT、Claude Code 和 Cursor 的英文设置说明： https://mistico.gustavocancado.com.br/en。在 Claude Code 中快速开始： claude mcp add --transport http --scope user ceu-natal https://astrologia-mcp.gustavocancado.com.br/mcp/。

为何存在

向 AI 助手索要星盘时，它往往会自信地作答，但星体位置常常是编造的：模型没有星历，因此会猜测月亮星座和上升星座。此服务会真正计算并返回数据；AI 只负责解读。

立即使用

免费公共 MCP 端点（Streamable HTTP，无需登录）：

https://astrologia-mcp.gustavocancado.com.br/mcp/

Claude、ChatGPT、Gemini、Manus、Cursor 和 n8n 的逐步说明： https://mistico.gustavocancado.com.br/#conectar。

可计算的内容

工具	功能
calcular_mapa_natal	计算出生星盘的位置、宫位、角度、相位、交点、凯龙星和概要。
calcular_sinastria	计算两个人之间的交叉相位，以及一方的行星落入另一方宫位的情况。
calcular_transitos	计算指定日期的星体位置、与出生星盘的相位，并突出显示慢速行星的行运。
calcular_progressoes	计算次限推运（1 天 = 1 年），包括推运月亮和太阳。
calcular_mapa_composto	使用中点法计算两个人的组合星盘。
calcular_revolucao_solar	计算某一年的太阳回归星盘，并指定回归地点。
calcular_revolucao_lunar	从指定日期起计算下一次月亮回归至出生位置的时间。
listar_aspectos_tipos	列出支持的相位、角度、容许度和性质。
healthcheck	服务状态和版本。

个人输入：data（DD/MM/YYYY，必填）、hora（HH:MM）、local （“城市，州”或“城市，国家”）、nome、is_dst。如果出生星盘未提供 hora，计算将使用当地时间 12:00，月亮位置会标记为不确定（posicao_incerta、signo_pode_mudar），并且不提供宫位或角度。sistema_casas 为可选项：P Placidus（默认）、K Koch、 W Whole Sign、E Equal、R Regiomontanus、C Campanus、O Porphyrius、B Alcabitus、 M Morinus、T Topocentric。GET /tools 会列出工具及参数名称；完整的 inputSchema 可通过 MCP 的 tools/list 获取（任何 MCP 客户端都能查看）。

示例

请求（tools/call）：

{
  "name": "calcular_mapa_natal",
  "arguments": {"nome": "Ana", "data": "12/03/1990", "hora": "14:30", "local": "Belo Horizonte, MG"}
}

响应片段：

{
  "planetas": {
    "sol": {"signo": "Peixes", "grau": "21°52'", "grau_decimal": 21.8779, "posicao_absoluta": 351.8779,
            "retrogrado": false, "elemento": "Agua", "qualidade": "Mutavel", "casa": 8},
    "lua": {"signo": "Libra", "grau": "6°19'", "grau_decimal": 6.329, "posicao_absoluta": 186.329,
            "retrogrado": false, "elemento": "Ar", "qualidade": "Cardinal", "casa": 3}
  },
  "angulos": {
    "ascendente": {"signo": "Cancer", "grau": "18°38'", "grau_decimal": 18.6412, "posicao_absoluta": 108.6412}
  },
  "aspectos": [
    {"planeta_a": "lua", "planeta_b": "venus", "tipo": "trigono", "orbe": 0.48,
     "aplicando": true, "exato": true, "natureza": "harmonico"}
  ],
  "local_resolvido": {"lat": -19.9167, "lng": -43.9333, "fuso": "America/Sao_Paulo"}
}

完整响应还包含其他行星、12 个宫位、天顶、下降点、天底、敏感点和概要（元素、性质、 半球、星群）。

本地运行

使用 Docker：

cp .env.example .env
docker compose up --build        # http://localhost:8000

使用 pip（Linux 或 macOS；Windows 上请使用 WSL，因为 pyswisseph 无法在 Windows 上编译）：

python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.server:app --port 8000

通过 stdio 运行，适用于只能启动本地进程的客户端：python -m app.stdio（环境变量相同）。

路由：/mcp/（MCP Streamable HTTP）、/health、 /tools（工具列表；当 MCP_API_KEY 为空时公开）、/llms.txt、 /mapa-rapido（网站表单）以及 /（重定向至 PUBLIC_SITE_URL）。

要参与开发，还需安装 requirements-dev.txt，并运行 ruff check .、mypy app 和 python -m pytest -q。详情见 CONTRIBUTING.md。

环境变量

变量	默认值	描述
MCP_SERVER_NAME	ceu-natal	在 initialize 中返回的名称
MCP_SERVER_VERSION	2.2.6	对外公开的版本
MCP_API_KEY	(空)	如果已设置，则要求提供 Authorization: Bearer <chave>；为空时，允许所有请求
MCP_ALLOWED_HOSTS	(空)	/mcp/ 接受的主机（防 DNS 重绑定），以逗号分隔；为空 = 不验证
RATE_LIMIT_SESSION_PER_MIN	30	每个 MCP 会话每分钟的工具调用次数（0 表示关闭）
RATE_LIMIT_GLOBAL_PER_MIN	600	总计每分钟的工具调用次数（0 表示关闭）
RATE_LIMIT_MAPA_RAPIDO_IP_PER_MIN	6	每个 IP 每分钟对 /mapa-rapido 的请求次数（0 表示关闭）
RATE_LIMIT_MAPA_RAPIDO_GLOBAL_PER_MIN	120	总计每分钟对 /mapa-rapido 的请求次数（0 表示关闭）
PUBLIC_SITE_URL	https://github.com/gucancado/ceu-natal	/ 和 /llms.txt 的重定向目标（跳转至 <site>/llms.txt）
CORS_ORIGINS	(空 = PUBLIC_SITE_URL)	/mapa-rapido 的 CORS 接受的源，以逗号分隔
GEONAMES_USERNAME	(空) — 未设置时仅使用 Nominatim	用于地理编码的 GeoNames 账户（在 geonames.org 免费创建自己的账户）
NOMINATIM_USER_AGENT	ceu-natal-mcp/2.0	发送给 Nominatim（OSM）的 User-Agent
NOMINATIM_MIN_INTERVAL_S	1.0	Nominatim 调用之间的最小间隔（秒）
GEOCODER_MAX_CONCORRENTES	4	地理编码服务提供商的最大并发调用数
GEOCODER_ESPERA_MAX_S	3.0	等待空位的最长时间（秒）；超时后返回错误
GEOCODER_CACHE_PATH	<tmp>/ceu-natal-geocode-cache.json	坐标持久化缓存；在 Docker 中，卷位于 /var/cache/ceu-natal
CONTATOS_PATH	空（关闭 /contato）	网站上留下的资讯订阅联系人 JSONL 文件；生产环境中为 /var/lib/ceu-natal/contatos.jsonl（持久化卷）
ESTATISTICAS_PATH	空（关闭 /estatisticas）	使用情况汇总统计数据的 SQLite 数据库（状态页面）；生产环境中为 /var/lib/ceu-natal/estatisticas.sqlite3（持久化卷）
HISTORICO_PATH	空（不保存任何内容）	网站表单生成的星盘 SQLite 数据库（日期、时间、城市），关联至浏览器匿名 ID 和联系人；生产环境中为 /var/lib/ceu-natal/historico.sqlite3
CONTATOS_ADMIN_TOKEN	空（/contatos 返回 404）	GET /contatos（包含每位联系人的星盘）和 GET /historico（按浏览器查看历史记录）路由的 Bearer 令牌；与 MCP_API_KEY 分开

网站（web/）

介绍网站（https://mistico.gustavocancado.com.br）是一个独立的 Next.js 16 应用， 使用自己的 Docker 镜像（web/Dockerfile）。运行方式： cd web && pnpm install && pnpm dev；URL 配置来自 web/.env.example。

精度与限制

• 星历： 使用 Astrodienst AG 的 Swiss Ephemeris，通过 Kerykeion 和 pyswisseph 提供。热带黄道。
• 纬度高于 66°： 靠近两极时，宫位计算不可靠。生成的本命盘不包含宫位或角度，并附有警告；行运、推运和回归盘请求会被拒绝。
• 年份： 日期范围为 1800 至 2399 年（凯龙星星历的范围）；太阳回归盘范围为 1800 至 2200 年。
• 夏令时： 如果时间落在切换时段（存在歧义或时间不存在），服务端会返回错误，要求提供 is_dst（true = 夏令时，false = 标准时间）。
• 出生时间未知： 按当地时间 12:00 计算；月亮可能位于其每日运动范围的前半段或后半段（通常为 6° 至 7.6°，通过 margem_graus 返回），结果会说明月亮星座何时可能改变。
• 公共端点限制： 每个会话每分钟 30 次调用，总计每分钟 600 次调用。通过 MCP 接收的内容不会被存储（网站表单生成的星盘会保存）；请参阅 隐私政策。

贡献

欢迎提交 Issue 和 pull request。请参阅 CONTRIBUTING.md；如有安全漏洞， 请参阅 SECURITY.md。

许可证

AGPL-3.0-or-later。AGPL 也适用于网络使用：以修改后的形式将此 服务作为服务提供的用户必须公开代码。公共端点运行的正是本仓库中的代码。

版权所有 (C) 2026 Gustavo Cançado。第三方致谢和许可证见 NOTICE。

许可证选择遵循依赖项的许可：Kerykeion 采用 AGPL-3.0，而 pyswisseph（Swiss Ephemeris） 采用 AGPL-3.0 或 Astrodienst 的付费专业许可证。若要以不符合 AGPL 条款的方式使用， 则需要获取 Swiss Ephemeris 专业许可证并替换 Kerykeion。网站使用 @beeads/* 软件包， 这些软件包采用与 AGPL 兼容的 MIT 许可证。