nasa-power-mcp-server

---

概述

NASA POWER 提供历史太阳能和气象观测数据，适用于可再生能源、可持续建筑和农业气候学。获取点位时间序列和气候学数据，查看原生网格区域，并比较带标签的位置及其源单位和溯源信息。无需 NASA 账户或 API 密钥。

工具

工具	描述
nasa_power_get_timeseries	获取单个点位的每小时、每日或每月观测数据
nasa_power_get_climatology	获取点位的月度和年度气候学数据，包括倾斜太阳能剖面
nasa_power_get_region	获取有界原生网格区域内的单个参数
nasa_power_compare_locations	获取 2–10 个带标签点位的共享观测数据和季节摘要
nasa_power_search_parameters	搜索完整的社区／分辨率参数字典
nasa_power_list_reference	查看预设、社区、覆盖范围、缺失值、风能表面和 DataFrame 使用指南
nasa_power_dataframe_describe	查看暂存架构、单位、有效期和溯源信息
nasa_power_dataframe_query	使用明确指定的画布令牌运行有界只读 SQL
nasa_power_dataframe_drop	选择性移除一个指定的暂存表

默认启用 8 个工具；设置 NASA_POWER_DATAFRAME_DROP_ENABLED=true 可启用第 9 个工具。

能力参考

nasa_power_get_timeseries _工具

• latitude / longitude 和 temporalResolution：hourly 和 daily 需要提供包含首尾日期的 startDate / endDate，monthly 需要提供 startYear / endYear。selection 是具名 preset（默认值为 solar_pv）或显式指定的 parameters，每小时最多 15 个有效代码，其他情况最多 20 个，包含校正项。
• community（RE、SB、AG；默认值为 RE）、units（metric、imperial）和 timeStandard（LST、UTC）。可选的 siteElevation 会添加 PSC；成对提供 windElevation（10–300 米）和 windSurface 会添加 WSC。使用 nasa_power_list_reference 的 wind_surfaces 主题查看全部 17 个规范 NASA 别名，包括 airportgrass、airportice 和 vegtype_1；植被类型中的下划线会保留。
• 返回 metadata、parameters、expansions、omittedParameters、summaries、rows、精确的 rowCount 和 dataset（除非已暂存，否则为 null）。需要暂存时，可选的 canvas_id 可复用画布。

---

nasa_power_get_climatology _工具

• 点坐标使用相同的选择和校正项；可选的 startYear 和 endYear 必须成对提供，否则使用源产品的时间范围。不接受 temporalResolution 输入。
• 小型概况以内联形式返回；较大的概况会返回有界预览和完整的 dataset 句柄。传入可选的 canvas_id 可复用现有工作区。没有 DuckDB 时，请缩小超大选择范围，以便以内联形式输出。SI_EF_TILTED_SURFACE 以及不同的 SI_TILTED_AVG、SI_TILTED_MIN、SI_TILTED_MAX 组，会在 expansions 中仅列出实际返回的成员，并包含数值角度和 N/S 朝向文本。只有当某组的所有成员均未返回时，才会省略该组。

---

nasa_power_get_region _工具

• 对按序排列的 latitudeMin / latitudeMax 和 longitudeMin / longitudeMax 指定的区域使用一个 parameter；每个轴跨度为 2–10 度（否则返回 invalid_region）；跨越日期变更线的区域需拆分为多个调用。temporalResolution 为 daily、monthly 或 climatology；不支持点位校正。
• 每日区域必须提供日期范围，每月区域必须提供年份范围。区域气候态不接受年份字段，并会报告源数据预先计算的时段；如需自定义点位年份范围，请使用 nasa_power_get_climatology。
• 返回带单元格标签的 rows、cellCount 和按时段汇总的 summaries，其中 min / mean / max 为单元格等权值，而非面积加权值。暂存时，可选的 canvas_id 可复用画布。
• 汇总数据量超出响应限制时，会返回包含所有跨单元格汇总的 summaryDataset、精确的 summaryCount 和完整记录的内联预览。按 summaryIndex 顺序查询该表；SQL 中的 units: null 表示省略了源单位。观测值和汇总数据会一并注册，并保留相互关联的来源信息。

---

nasa_power_compare_locations _工具

• 提供 2–10 个 locations，每个都包含坐标和长度为 1–120 个字符的 label，并共用一组选择、校正项和时间范围。temporalResolution 默认值为 climatology；也支持 hourly、daily 和 monthly。
• 返回成功的 locations 及其每个站点的来源信息、带位置标签的 rows、年度和日历季节 summaries，以及失败的 failed 条目；部分站点失败时会标记 partial: true；所有站点均失败时返回 all_locations_failed。possibleSharedGridCell 表示站点可能共用一个网格单元。
• 可选的 sort（parameter、direction asc / desc）会按选定的数值参数排序，且该参数的单位已知并相同。暂存时，可选的 canvas_id 可复用画布。
• 汇总数据超出响应限制时，summaryDatasets.buckets 和 summaryDatasets.locations 会指向完整的 SQL 表；内联汇总会成为完整记录预览，每个位置均包含 summaryCount。按 summaryIndex 顺序查询；位置汇总表包含 locationId。SQL 中的 units: null 表示源单位已省略，并不表示单位已知。

nasa_power_search_parameters _工具

• community（默认值为 RE）、temporalResolution（默认值为 daily）、可选的 filter（最多 256 个字符）、offset 和正整数 limit（默认值为 20，实际上限为 100，达到上限时会显示提示）。
• 在排序和分页之前，filter 中的每个不区分大小写的词元都必须与完整字典中的代码、名称或定义匹配；空白筛选条件可用于浏览字典。entries、total、hasMore 和 truncated 描述当前页。

---

nasa_power_list_reference _工具

• topic：presets（默认值）、communities、coverage、missing_data、wind_surfaces 或 dataframes。
• 返回类型化的 entries、guidance、documentationUrls 和 verifiedOn。预设包括 solar_pv、wind_turbine、building_hvac、agroclimatology 和 water_balance；building_hvac 不提供小时级数据。除小时级分辨率外，agroclimatology 会添加 T2M_MAX 和 T2M_MIN；月度／气候态极值仍为源数据聚合值，不会重建每日记录，也不会计算生长度日。

---

nasa_power_dataframe_describe _工具

• 必需的 canvas_id 来自生成数据的响应；可选的 table 用于将检查范围限定为一个表。
• 返回画布和表的过期时间、带源单位的 SQL 列，以及原始科学 provenance。只能查看所提供画布中的表。

---

nasa_power_dataframe_query _工具

• 必需的 canvas_id 和 sql 中的一条只读 SELECT 语句（最多 16,384 个字符）；正整数 rowLimit 默认值为 100，上限为 1,000，超过上限的请求会显示实际生效上限的提示。禁止访问文件、执行写入操作和查询系统目录。
• 返回 columns、rows、rowCount、shownCount、truncated 和 countSemantics（exact 或 materialized_prefix）。SQL 执行时限为 10 秒；结构化输出和呈现输出均不得超过 40,000 个字符。
• SQL 错误会保留有界的标识符或转换值，并提供恢复指导。运行故障仅使用通用消息；不显示引擎路径和原生错误原因。

---

nasa_power_dataframe_drop _工具

• 必需的 canvas_id 和准确的 table；仅当 NASA_POWER_DATAFRAME_DROP_ENABLED=true 时启用。
• 如果表不存在，则返回 dropped: false，其他表仍会使画布保持有效。移除最后一个表也会注销其画布并释放其槽位；之后调用 describe、query 或 drop 均会返回 canvas_not_found。

功能

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

POWER 专属功能：

• 历史网格观测数据，而非站点测量值或预报。气象数据覆盖始于 1981 年，太阳能数据始于 1984 年，小时数据始于 2001 年；数据源配置和发布延迟也会进一步限制可用性。
• 每次仅允许一个上游请求，启动间隔至少为两秒；重试次数有上限，单次调用的总时限为 55 秒。NASA 未公布数值化的请求配额。参考数据缓存 24 小时，观测数据缓存 10 分钟。
• 源数据中的填充值会转换为 null；零仍视为测量值。月度年键和气候平均值 ANN 与月度观测值保持区分。LST 标签不含 UTC 偏移量。
• T_ZONES 和 TM_ZONES 保留数值型气候区代码，并标记为 valueKind: categorical，SQL 列元数据中也如此处理。它们不支持算术汇总或比较排序指标；不允许对其中任一列进行显式数值排序。

面向 Agent 的输出：

• 科学溯源信息——结果附带来源 API 版本、数据集标识符、端点和访问时间；请保留返回的单位，并注明数据来自 NASA POWER。
• 明确的数据缺口——omittedParameters 用于区分缺失的序列与填充值；观测数据的算术平均值和日历季节分组不代表气候常值、年度产量或水量平衡。
• 完整数据集——每个内联输出均不超过 40,000 个字符。较大的数据集会暂存所有行，并提供最多 20 行的预览和 dataset 句柄；不受支持或超出限制的请求会失败，并提供缩小请求范围的指引，而不是返回截断后的源数据前缀。

暂存需要 DuckDB，每个数据集最多支持 250,000 行、64 个参数列和 32 MiB 的序列化行数据。Canvas 是进程本地的能力：请显式传递返回的令牌，并将后续调用路由到同一进程。表格在 30 分钟后过期，每个 canvas 最多可有八张表。默认情况下，每个 canvas 的空闲时长为一小时，绝对时长为六小时；每个租户最多四个 canvas，每个进程最多八个 canvas，每个 canvas 的引擎内存为 256 MiB。运维人员可在下方配置 canvas 容量、内存和生命周期；引擎内存不限制总 RSS 或临时磁盘空间。

快速入门

公共托管实例

可使用公共实例 https://nasa-power.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端连接到该实例：

{
  "mcpServers": {
    "nasa-power-mcp-server": {
      "type": "streamable-http",
      "url": "https://nasa-power.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

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

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

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

如需使用 Streamable HTTP，请设置传输方式并启动服务：

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

前置要求

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 在受支持的平台上，npm 和 Docker 会正常安装 DuckDB 原生依赖项，且默认启用暂存和 SQL。设置 CANVAS_PROVIDER_TYPE=none 可使所有结果以内联方式返回。
• 便携版 Claude Desktop MCPB 包会将 CANVAS_PROVIDER_TYPE=none 固定为该值，并支持内联结果。对于超出限制的请求，请缩小请求范围，或使用 npm/Docker 进行分析。

安装

1. 克隆代码库：

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

2. 进入目录：

cd nasa-power-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env to change transport, logging or canvas settings

配置

变量	描述	默认值
NASA_POWER_DATAFRAME_DROP_ENABLED	显式开放暂存表移除功能。	false
CANVAS_PROVIDER_TYPE	duckdb 会为 npm/Docker 上的 SQL 暂存大型结果；none 会将结果保留为内联数据。MCPB 固定使用 none。	duckdb
CANVAS_DEFAULT_MEMORY_LIMIT_MB	每个画布的引擎内存，整数且 ≥64 MiB；不代表总 RSS 或临时磁盘空间。	256
CANVAS_MAX_CANVASES_PER_TENANT	每个租户的画布数量上限，必须为正数；使用 auth-none 的调用方共用一个租户。	4
NASA_POWER_MAX_CANVASES_PER_PROCESS	每个进程的画布数量上限，必须为正数，包括待处理和清理失败的预留项。	8
CANVAS_TTL_MS	以毫秒为单位的滑动式画布生命周期，必须为正数。	3600000
CANVAS_ABSOLUTE_CAP_MS	以毫秒为单位的画布绝对生命周期，且不得短于滑动式 TTL。	21600000
MCP_TRANSPORT_TYPE	stdio 或 http。	stdio
MCP_HTTP_HOST / MCP_HTTP_PORT	HTTP 绑定地址和端口。	127.0.0.1 / 3010
MCP_AUTH_MODE	none、jwt 或 oauth。	none
MCP_LOG_LEVEL	最低日志级别。	info
OTEL_ENABLED	启用 OpenTelemetry。	false

未设置、空白和整个值为占位符的设置会保留这些默认值。无效的规格设置会导致启动失败。字节预算、表限制和生产者并发数不受操作员设置的画布规格影响，保持固定。可选的传输、身份验证、存储、日志记录和遥测设置请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

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

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker build -t nasa-power-mcp-server .
docker run --rm -p 127.0.0.1:3010:3010 nasa-power-mcp-server

镜像默认使用 HTTP，在端口 3010 上以无状态会话模式运行，并将日志写入 /var/log/nasa-power-mcp-server。默认会安装 OpenTelemetry 对等依赖项；如要省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。对于来自环回地址之外的客户端，请在部署边界配置身份验证和 TLS。

项目结构

路径	用途
src/index.ts	九个工具的注册、有界画布设置和服务关闭
src/config	工作负载限制和服务专用的环境变量解析
src/mcp-server/tools/definitions	工具契约和比较编排
src/services/power	按节奏调用的 NASA 客户端、规范化、预设和科学摘要
src/services/canvas	显式令牌暂存、SQL、来源信息和准入限制
scripts	构建、验证、打包和发布工具
tests	离线契约和原生集成测试

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要内容如下：

• 处理器抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.signal 处理取消
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段，并保留源单位和年度周期的区别
• content[] 和 structuredContent 携带相同的完整数据

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。