astronomy-mcp-server

---

概述

适用于任意地点和时间的观测天文学：天体位置、升起和落下时间及曙暮光时间、月相，以及下一次日食、春分或秋分、冲或合——也可以直接询问此刻能看到什么。由 astronomy-engine 在本地计算，并可选使用 JPL Horizons 星历和卫星过境信息。

工具

工具	描述
astronomy_get_sky_position	单个天体或指定恒星的视位置：赤经/赤纬、地平高度/方位角、黄道坐标、视星等、相位、日距角、星座
astronomy_get_rise_set	天体的升起、落下和中天时间；以及太阳的民用、航海和天文曙暮光时间
astronomy_get_moon_phase	照明比例、月相名称、朔望月龄，以及接下来的四个盈亏相位
astronomy_find_events	下一次日食、春分或秋分、至点、月相四分点、冲、合、大距或远近日点事件
astronomy_list_visible	当前可见天体：地平线以上肉眼可见的天体（以及可选的亮星），按排名列出，并提供天空状况筛选
astronomy_get_ephemeris	从 JPL Horizons 获取小天体或航天器星历（可选）
astronomy_get_satellite_passes	根据 CelesTrak 轨道根数集通过 SGP4 传播计算可见卫星过境信息（可选）

资源

资源	描述
astronomy://body/{body}	太阳系天体参考卡片：名称、类型、平均半径、肉眼可见性

仅支持工具的客户端也能从 astronomy_get_sky_position 获取相同的类型、半径和肉眼可见性字段。

提示词

提示词	描述
astronomy_stargazing_plan	从某个地点规划一晚观星活动，并串联天文学工具、地理编码和天气步骤

设计参考：docs/design.md。

功能参考

astronomy_get_sky_position _工具

• 必须提供 body（sun、moon、mercury … pluto）或 star；两者都设置时以 star 为准。star 会根据常用名称或拜耳命名（Sirius、α CMa）在内置的 32 颗恒星目录中查找；找不到时会返回 star_not_found，并列出该目录
• 返回 equatorial、经折射校正的 horizontal 和 ecliptic 坐标，以及 magnitude、angular_diameter_arcsec、phase_angle_degrees、illuminated_fraction、sun_elongation_degrees 和 constellation
• 太阳系天体还会包含 body_metadata、资源卡片的 type、mean_radius_km 和 naked_eye；恒星则不包含这些字段

---

astronomy_get_rise_set _工具

• 搜索一个 body，从 start（默认当前时间）开始，向后查找接下来的 count 个周期，默认值为 1。每次调用最多返回 31 个周期；若 count 不超过 366，则返回前 31 个周期，并通过提示说明用于继续查询序列的 start 和 count
• 每个周期包含 rise_utc、set_utc、transit_utc 和 transit_altitude_degrees；对于拱极天体或永不升起的天体，rise 和 set 为 null，并提供 note，而不是报错
• 对于 body: "sun"，twilight 包含每个周期所对应日期之后夜晚的民用、航海和天文暮光及黎明时段。若第一个日期在 start 之后开始，night_in_progress 会包含此前的夜晚，包括没有日落的极夜；否则第一个周期会包含自身对应的夜晚。每组时段都不会超出该夜晚的范围，并且仍会包含早于 start 的时刻

---

astronomy_get_moon_phase _工具

• 地心观测：仅接受 time（默认当前时间）和可选的 timezone
• 返回 illuminated_fraction、phase_name、age_days、next_quarters 和 phase_longitude_degrees（0 表示新月，180 表示满月）；此字段不同于 astronomy_get_sky_position 的 phase_angle_degrees

---

astronomy_find_events _工具

• 查询一种 event（solar_eclipse、lunar_eclipse、equinox、solstice、moon_quarter、opposition、conjunction、max_elongation、perigee_apogee）及其接下来的 count 次发生，默认值为 1。每次调用最多返回 20 次；若 count 不超过 200，则返回前 20 次，并通过提示说明用于继续查询序列的 start 和 count；搜索截止于 2100 年底
• 与天体相关的事件必须提供 body（否则返回 body_required）；若该事件不适用于指定天体，则返回 body_not_supported。conjunction 若提供 body2，则该值必须是月球或不同于 body 的行星（否则返回 invalid_body_pair），并会报告 separation_degrees
• 日食和月食可选提供观测者位置（必须同时提供 latitude 和 longitude，否则返回 incomplete_observer），以添加 local_visible 和 contact_altitudes_degrees
• 日食和月食若其峰值发生在 start 或之后，则会被纳入；其接触时刻可能早于 start

---

astronomy_list_visible _工具

• 提供观测者坐标和一个评估时刻 time（默认当前时间，不是时间窗口）；min_altitude（默认 0）和 include_stars（默认 false）用于筛选列表
• 返回 sky_condition（daylight、civil_twilight、nautical_twilight、astronomical_twilight、dark）、sun_altitude_degrees，以及按亮度和高度从高到低排序的 bodies。每个天体都附有 visibility_note，说明日光、民用暮光或太阳周围 15° 内的强光何时会遮蔽或削弱其可见度

---

astronomy_get_ephemeris _工具

• designation 会原样传递给 Horizons（编号小行星使用 "433;"，周期彗星使用 "DES=1P;CAP"，航天器使用负数 SPK-ID）；start 默认为现在，stop 默认为 24 h 后，step 默认为 "1h"（数字加上 m、h、d、mo 或 y）；同时提供 latitude 和 longitude 时会添加高度角/方位角
• 每次调用最多返回 200 行；当 truncated 为 true 时，提示会指出可用于继续查询的 start。target_name 是 Horizons 解析出的天体名称
• 失败时会返回 ambiguous_designation、observer_is_target、body_not_found、invalid_step、invalid_elevation、time_out_of_range 或 request_rejected，并指出需要更正的输入
• 仅当 ASTRONOMY_ENABLE_HORIZONS=true 时注册

---

astronomy_get_satellite_passes _工具

• norad_id 和 name 必须且只能提供一个（ISS、Hubble/HST 和 Tiangong/CSS 可直接解析；其他名称会与 CelesTrak 匹配，若名称不明确，则会返回 ambiguous_satellite_name 并列出候选项）；start 必须在距今天约一个月的范围内，days 默认为 7
• 每次调用搜索 10 天；days 最大可设为 30，但只返回前 10 天的结果，并提示可用于继续搜索的 start 和 days
• 返回 norad_id、satellite_name 和符合可见条件（受日照、高度角高于 10°、太阳低于 −6°）的 passes；每项包含升起/最高点/落下时间及方位角、peak_altitude_degrees、duration_seconds、sunlit 和 visible_start_utc/visible_end_utc
• 仅当 ASTRONOMY_ENABLE_SATELLITES=true 时注册

---

astronomy://body/{body} _资源

• {body} 可以是 sun、moon、mercury … pluto 中的一个，并支持名称补全；其他值会返回 unknown_body
• application/json 卡片包含 body、name、type（star/planet/moon/dwarf）、mean_radius_km 和 naked_eye

---

astronomy_stargazing_plan _提示词

• 参数：必填的 location；可选的 date（YYYY-MM-DD），默认为今晚
• 返回一条用户消息，依次调用 astronomy_get_rise_set（先太阳，再月亮）、astronomy_get_moon_phase 和带有 include_stars 的 astronomy_list_visible，并包含此服务未覆盖的地理编码和天气步骤

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

天文学专属功能：

• 无需密钥、离线且确定性的核心：五个核心工具无需网络、API 密钥或速率限制；对于相同的天体、时间和观测者，返回相同结果
• 超出引擎高精度时间范围（约 1900–2100）的时间会返回 time_out_of_range；Horizons 工具则受各目标自身数据范围限制
• 时间采用 ISO 8601 UTC 格式；未指定时区的值会按 UTC 读取；传入 IANA timezone（或设置 ASTRONOMY_DEFAULT_TIMEZONE），即可在 UTC 字段之外获取 *_local 字段。服务绝不会根据坐标推断时区
• 不提供地理编码：请先在上游将地点名称解析为纬度、经度和时区，再传入坐标（elevation 默认为 0 m）
• 两个可选扩展各自具有超时和重试机制；上游故障会返回 horizons_unavailable 或 celestrak_unavailable，绝不会回退到核心输出

便于 Agent 使用的输出：

• 保留不确定性：引擎无法计算时，magnitude、angular_diameter_arcsec、phase_angle_degrees 和 illuminated_fraction 为 null，并显示为“unavailable”，绝不会置为零
• 确定性的可见性说明：visibility_note 根据真实星等、高度、天空状况和太阳距角生成，而非使用合成评分
• 类型化错误契约：每个已声明的故障都包含类型化的 reason 和恢复提示，以便调用方修正并重试
• 精确值保留在舍入文本中：format() 会将每个舍入后的数值与方括号中的精确值配对（RA 4.4116 h [4.411597993526305]），因此仅使用 content[] 的客户端也不会丢失精度

开始使用

公共托管实例

可使用公共实例：https://astronomy.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http astronomy-mcp-server https://astronomy.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "streamableHttp",
      "url": "https://astronomy.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "url": "https://astronomy.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。核心工具无需配置；设置 ASTRONOMY_ENABLE_HORIZONS 和/或 ASTRONOMY_ENABLE_SATELLITES 为 true，即可注册扩展。

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/astronomy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可通过 npx 运行（无需 Bun）：

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/astronomy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可通过 Docker 运行：

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/astronomy-mcp-server:latest"]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥。核心功能可离线运行，两个扩展（JPL Horizons、CelesTrak）也无需密钥。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/astronomy-mcp-server.git

2. 进入目录：

cd astronomy-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env only to enable the extensions or override a default

配置

所有变量均为可选项；不设置任何变量也能运行核心功能。

变量	说明	默认值
ASTRONOMY_ENABLE_HORIZONS	注册 astronomy_get_ephemeris（JPL Horizons）。	false
ASTRONOMY_ENABLE_SATELLITES	注册 astronomy_get_satellite_passes（CelesTrak + SGP4）。	false
ASTRONOMY_DEFAULT_TIMEZONE	调用未提供 timezone 时使用的备用 IANA 时区。未设置时仅输出 UTC。	无
ASTRONOMY_REQUEST_TIMEOUT_MS	Horizons 和 CelesTrak 请求的 HTTP 超时时间，单位为毫秒。	15000
ASTRONOMY_TLE_CACHE_TTL_MS	进程内轨道根数集缓存的 TTL，单位为毫秒。2 小时的默认值遵循 CelesTrak 的重新获取建议。	7200000
ASTRONOMY_HORIZONS_BASE_URL	JPL Horizons API 端点。	https://ssd.jpl.nasa.gov/api/horizons.api
ASTRONOMY_CELESTRAK_BASE_URL	CelesTrak GP 端点。	https://celestrak.org/NORAD/elements/gp.php
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t astronomy-mcp-server .
docker run --rm -p 3010:3010 astronomy-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/astronomy-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具、资源和提示词，并初始化服务。
src/config	使用 Zod 解析和验证特定于服务的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。包含五个核心工具和两个可选扩展。
src/mcp-server/resources	资源定义（*.resource.ts）。天体参考卡。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。观星计划。
src/services/ephemeris	离线计算核心 — astronomy-engine 封装、天体表和亮星目录。
src/services/horizons	JPL Horizons HTTP 客户端（扩展）。
src/services/satellite	获取 CelesTrak 轨道根数集并进行 SGP4 推算（扩展）。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 将引擎/API 的原始值规范化为领域类型；将不确定值保留为 null，绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。