noaa-spaceweather-mcp-server

---

概述

来自 NOAA 太空天气预报中心的太空天气信息：地磁暴、Kp 指数、极光预报、太阳风、太阳活动和当前警报。查看当前状况、了解当前位置是否能看到极光，或获取太阳风时间序列。

工具

工具	描述
noaa_spaceweather_get_conditions	当前空间天气概况：昨天、今天和未来 3 天的 NOAA R/S/G 风暴等级、最新 Kp、通俗易懂的状态摘要，以及可选的 SWPC 预报讨论，用于说明预报依据
noaa_spaceweather_get_kp_index	行星 K 指数（0–9）——近期观测到的 3 小时数值及其 G 级对应值、极光纬度参考，以及未来 3 天预报
noaa_spaceweather_get_aurora_forecast	OVATION 模型极光预报：全球概率网格；可选根据坐标查询本地预报，提供考虑日照情况的可见与否判定，以及极向地平线读数
noaa_spaceweather_get_solar_wind	来自当前 L1 航天器的实时太阳风数据：速度、质子密度、温度，以及关键的 Bz 分量和时间窗口内最偏南的读数——说明当前地磁状况的成因
noaa_spaceweather_get_solar_activity	太阳耀斑概况：包含峰值等级和 R 级的单次耀斑事件、GOES X 射线通量、每日 F10.7 cm 射电通量、未来 3 天的耀斑等级概率、活跃太阳区当天的耀斑计数和次日概率，以及太阳辐射风暴等级
noaa_spaceweather_get_alerts	当前有效的 SWPC 警报、监视和预警——结构化记录包含产品类型、严重程度、发布时间、有效时段和完整消息文本

能力参考

noaa_spaceweather_get_conditions _工具

• include_discussion（bool，默认值为 false）是唯一输入；一次调用会组合 noaa-scales.json 和 noaa-planetary-k-index.json 数据源，并在请求讨论内容时加入 discussion.txt 产品
• 返回当前 Kp 及其对应的 G 级和极光纬度参考、今天观测到的 R/S/G 等级、yesterday（前一个 UTC 日评估的等级；数据源中没有时为 null），以及从今天开始的 SWPC 未来 3 天预报——预报中的 R 和 S 以概率而非等级表示，等级为 null 表示没有预报等级，而非等级为 0
• 使用 include_discussion 时，返回预报员撰写的预报讨论，并按主题分节（太阳活动、高能粒子、太阳风、地球空间），每节包含其 24 小时摘要和未来 3 天预报文本

---

noaa_spaceweather_get_kp_index _工具

• window_days（1–7，默认值为 1）限定观测序列的时间范围，observedCount 报告匹配的读数数量；预报始终包含 SWPC 完整的未来 3 天序列，行数据标记为 estimated/predicted
• 每条记录包含 Kp、对应的 G 级及其标签，以及极光纬度参考。G 级遵循 SWPC 的三分之一级别下限——G1 从 Kp 4.67（5−）开始，只有 Kp 9 才是 G5

---

noaa_spaceweather_get_aurora_forecast _工具

• latitude/longitude（WGS84）是可选参数，但必须同时提供——单独提供其中一个会返回 invalid_coordinates。不提供坐标时，调用仅返回全局元数据：网格点数量、全球最高概率和峰值区域
• 提供坐标后，localLookup 包含最近的 1° 网格概率、地磁纬度、当地所需的最低 Kp 和 G 级、预报时间的太阳高度及 darkness 状态（day、civil_twilight、nautical_twilight、dark）、1000 km 范围内极向的最强读数（horizonMaxPercent、horizonMaxLatitude、horizonDistanceKm），以及是否可见的 verdict——日照时不可见，无论模型给出的概率如何
• OVATION 模型约每 5 分钟更新一次，预报约 30–60 分钟后的情况

---

noaa_spaceweather_get_solar_wind _工具

• window_hours（1–168，默认 3）用于截取数据流中的时间窗口。该数据流包含大约最近 24 小时的数据，采样间隔约为 1 分钟。resolution 设置序列的详细程度：reduced（默认值）将每个序列限制为 200 条记录，并保留每个数据桶中的最快风速和最偏南的 Bz；full 返回所有记录（24 小时内每个序列约 1,400 条）；summary 返回空序列和所有摘要字段，约 2 KB
• 返回按时间从早到晚排列的等离子体（速度、密度、温度）和磁场（GSM 坐标系下的 Bx/By/Bz/Bt）序列，每条记录均标明其航天器；此外，在所有分辨率下，还会返回基于整个时间窗口计算的摘要字段：bzStatus、bzMinInWindow、speedMaxInWindow、densityMaxInWindow、btMaxInWindow 和 bzSouthMinutesInWindow
• latestFeedPlasmaTime/latestFeedMagTime/feedStalenessHours 可区分时间窗口为空和数据流已过期的情况

---

noaa_spaceweather_get_solar_activity _工具

• flare_hours（1–168，默认 24）用于限定按起始时间筛选的耀斑事件范围；数据流覆盖滚动 7 天。include_regions（默认值为 true）用于切换是否包含各活动区的详细信息，以控制响应大小
• 返回离散的耀斑事件，包括起始、峰值和衰减等级、峰值通量，以及对应的 NOAA R 等级（0–5）（耀斑仍在进行时，衰减等级为 null；SWPC 未记录峰值时，峰值字段为 null）；GOES X 射线通量及其耀斑等级（flareClassFull）；每日 F10.7 cm 射电通量及其观测时间；3 天 C/M/X 级耀斑和质子事件概率（cClassProbability、mClassProbability、xClassProbability、protonEventProbability——已弃用的 *1Day 名称仍会在 structuredContent 中提供这些概率）；以及根据 ≥10 MeV 质子通量确定的 S 等级
• 启用 include_regions 后，还会返回各活动区的黑子面积、SWPC 在其观测日归因于该活动区的 C/M/X 级耀斑数量，以及其次日耀斑概率

---

noaa_spaceweather_get_alerts _工具

• active_only（默认值为 true）仅保留当前有效的警告、观察和警报，并排除已取消或被取代的产品、摘要，以及有效期已结束的产品。max_age_hours（1–720，默认 48）限定候选产品的回溯时间范围——启用 active_only 时，有效期尚未结束的产品仍会保留；否则，该参数就是严格的时间范围限制
• 每条记录都包含产品类型、NOAA 等级和级别（0 表示“未注明等级”，并非严重性为零）、序列号、解析后的有效期、cancelled 标记和完整消息文本。启用 active_only 时，响应还会按原因统计排除的产品数量，因此结果为空时，可以判断是“当前无活动”还是“所有产品均已过滤”

---

功能

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

SWPC 专属功能：

• 所有 SWPC 数据源均公开且无需密钥，不需要 API 密钥
• 单个 SpaceWeatherService 封装了所有 NOAA SWPC 数据源（包括 JSON 产品和纯文本预报讨论），统一通过一个 fetchWithTimeout + withRetry 流程处理，因此两条路径会以相同方式分类上游故障；每个重试阶梯都在一个 45 秒预算内运行，因此即使上游挂起，也会在 60 秒客户端超时前返回已分类的错误
• 异构数据源规范化：交错的多航天器记录（太阳风）、键值对象（风暴等级）、坐标三元组（OVATION）、按分节文本（预报讨论）
• NOAA 等级解读：原始 Kp 6 →“G2 中等风暴——极光可能出现在地磁纬度约 55°以内”
• 在每条响应中呈现数据源新鲜度：太阳风约每 1 分钟更新一次，极光约每 5 分钟更新一次，Kp 每 3 小时更新一次

便于 Agent 使用的输出：

• 每条响应都包含观测时间戳，便于 Agent 判断数据新鲜度
• 除原始值外，还提供通俗易懂的摘要和判定，Agent 无需重新解读指数即可展示或推理
• 在太阳风输出中将 Bz 分量作为一等字段呈现（向南的 Bz 是风暴的主要驱动因素）
• 提供带恢复提示的类型化错误契约，并区分重试是否有用：临时数据源故障为 feed_unavailable →“30–60 秒后重试”；SWPC 已不再提供的数据源路径为 feed_moved →“重试无济于事”，并在首次尝试时抛出

---

快速开始

公共托管实例

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

Claude Code：

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

Cline（cline_mcp_settings.json）：

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

Cursor（mcp.json）：

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

在 Claude Desktop 中，可通过“设置” →“连接器”添加远程服务。

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

{
  "mcpServers": {
    "noaa-spaceweather": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/noaa-spaceweather-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 密钥，所有 SWPC 数据源均为公开数据。

安装

1. 克隆代码库：

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

2. 进入目录：

cd noaa-spaceweather-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if needed — all defaults work out of the box

---

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_HOST	HTTP 服务的主机名。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式。本项目明确使用 stateless；auto 会解析为 stateful。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，并按键名脱敏；日志大小上限由 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 设置（默认 16384）。自由格式值中的密钥不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

无需特定领域的 API 密钥。可查看 .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 noaa-spaceweather-mcp-server .
docker run --rm -p 3010:3010 noaa-spaceweather-mcp-server

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

---

项目结构

路径	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/services/space-weather/	SpaceWeatherService——获取并规范化所有 NOAA SWPC 数据源。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）——每个工具对应一个文件。
tests/	与 src/ 结构对应的单元测试和集成测试。
docs/	设计文档和目录树。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要来说：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/tools/definitions/index.ts 中的汇总文件注册新工具
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

---

贡献

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

bun run devcheck
bun run test

---

许可证

Apache-2.0——详情请参阅 LICENSE。