bhoonidhi-mcp

bhoonidhi-mcp

一个 MCP 服务，可让 AI Agent 通过自然语言搜索、保存、下载卫星影像，并将其加入购物车，这些影像来自 ISRO 的 Bhoonidhi Browse & Order 门户（NRSC）。Agent 可以将“去年 1 月，Shillong 上空的 Sentinel-2”这样的句子转化为对实时门户的实际搜索，准确查看哪些影像可供下载，保存搜索以供日后重用，预览下载将获取的内容，并在登录后下载开放获取的影像或将其加入购物车。

它是对 bhoonidhi-downloader SDK 的轻量封装——与 bhd CLI 使用同一个客户端，因此不会重复实现门户逻辑。

状态

无需登录即可搜索和保存；登录后即可下载并使用购物车。 这些工具可访问包含 41 个卫星任务和 79 个传感器的完整档案，搜索实时门户，并将搜索保存为可重复使用的 slug——这些操作都无需凭据。下载开放获取的影像以及将影像加入 Bhoonidhi 购物车需要登录；登录需通过 bhd auth login 在带外完成（服务会重用该会话）。

工具

工具	功能	登录
list_archive	门户支持的卫星、传感器和搜索词汇，数据实时来自 Bhoonidhi。	否
resolve_location	将地点名称（“Loktak Lake”）转换为中心点和边界框。不接受非地点名称的输入。	否
search_scenes	在指定区域和日期范围内进行自然语言场景搜索。将通俗的卫星名称解析为精确标记，并报告每个场景的可用状态（Ready / Archived / OnOrder / Priced）。无状态——不会保存任何内容。	否
preview_download	试运行：在实际下载前，展示下载结果会获取哪些内容，以及哪些内容会被跳过。	否
save_query	将搜索（参数与 search_scenes 相同）保存为可重复使用的 slug，以便稍后下载或暂存到购物车。	否
list_queries	以简洁摘要形式列出已保存的查询：slug、名称、日期范围、卫星、区域和可用状态。	否
show_query	按 slug 返回一个已保存的查询及其场景。	否
remove_query	按 slug 删除已保存的查询。	否
auth_status	报告是否已配置登录。绝不会处理密码或令牌。	否
download_query	在后台将已保存查询中的开放访问场景下载到服务器配置的固定根目录。立即返回 job_id。	是
download_status	单次检查 job_id 对应的后台下载：已下载字节数、传输速率、已知文件大小时的百分比，以及每个场景的详细信息。	否
download_wait	阻塞等待下载完成（或达到设定的超时时间上限），然后报告结果——这是后台监视器循环调用的高效基本操作。	否
cart_add	将已保存查询中的场景暂存到购物车（分别路由至 ready / on-order / priced）。	是
cart_list	列出当前暂存在购物车中的场景。	是
cart_remove	从购物车中移除场景。	是

可用状态很重要：OpenData 场景不一定已暂存以供下载。search_scenes 和 preview_download 会区分 Ready（立即获取）与 Archived（开放数据，但可能需要先在门户中提交请求），避免 Agent 过度承诺。

下载在后台运行，不受对话影响：download_query 会立即返回 job_id，传输会自行继续。使用 download_status 检查一次进度——它会报告已下载字节数、传输速率，以及已知文件大小时的百分比；也可以使用 download_wait 跟踪任务直至完成。它会一直阻塞到任务完成（或达到设定的超时时间上限），这样 Agent 就能委派后台监视器，而不必反复休眠轮询，从而让对话保持畅通。任务只在服务进程运行期间存在，因此一旦确认下载规模较大，状态信息会建议改为运行你自行管理的独立命令 bhd query download <slug>。

安装

该服务是一个带有控制台入口点 bhoonidhi-mcp 的 Python 包。最简单的运行方式是使用 uv——uvx 会直接从源代码获取、构建并启动它，无需克隆仓库或创建虚拟环境：

uvx --from git+https://github.com/geovicco-dev/bhoonidhi-mcp bhoonidhi-mcp

首次运行时会从源代码构建；之后的运行会从缓存启动。该服务通过 stdio 通信，并由 MCP 客户端启动——将客户端指向此命令即可。

更喜欢使用本地检出版本（用于开发）？克隆仓库并运行 uv sync，然后使用 .venv/bin/bhoonidhi-mcp 作为命令：

git clone https://github.com/geovicco-dev/bhoonidhi-mcp
cd bhoonidhi-mcp
uv sync

连接客户端

所有 MCP 客户端都需要同一项配置：启动命令。将客户端指向 uvx，并将源代码和入口点作为参数传入。

Claude Desktop / Claude Code

claude_desktop_config.json（或 claude mcp add）：

{
  "mcpServers": {
    "bhoonidhi": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/geovicco-dev/bhoonidhi-mcp", "bhoonidhi-mcp"]
    }
  }
}

OpenCode

~/.config/opencode/opencode.json：

{
  "mcp": {
    "bhoonidhi": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/geovicco-dev/bhoonidhi-mcp", "bhoonidhi-mcp"],
      "enabled": true
    }
  }
}

MCP Inspector（无需 Agent 即可试用）

npx @modelcontextprotocol/inspector uvx --from git+https://github.com/geovicco-dev/bhoonidhi-mcp bhoonidhi-mcp

示例

用通俗语言向 Agent 提问：

“2024 年 1 月，Shillong 上空有哪些 Sentinel-2 场景？其中有多少实际可以下载？”

Agent 会先调用 resolve_location 查找 Shillong，然后调用 search_scenes，并根据结果作答——例如，说明所有场景都处于 Archived 状态（属于开放数据，但可能需要先在门户网站上申请才能下载），而不是声称它们都已可供下载。

可尝试的提示词

将这些内容复制到任何已连接的 Agent 中，了解它能做些什么。

探索档案

• “Bhoonidhi 有哪些卫星和传感器？”
• “ResourceSat-2A 搭载了哪些传感器？分辨率是多少？”
• “Bhoonidhi 有雷达卫星吗？”

搜索场景

• “查找 2024 年 1 月 Shillong 上空的 Sentinel-2 场景。”
• “显示 2024 年上半年 Bengaluru 20 km 范围内的 Cartosat 影像。”
• “2024 年 3 月 Sundarbans 上空有 Sentinel-1 场景吗？”
• “去年冬天有哪些覆盖 Kaziranga National Park 的 Landsat-8 影像？”
• “查找 2023 年 12 月 Rann of Kutch 上空的 MODIS 场景。”

查看哪些场景可供下载

• “这些 Sentinel-2 场景中，现在有多少实际可以下载？”
• “哪些场景需要订购或付费？”

预览下载内容

• “预览下载这些场景会获取哪些内容。”

保存搜索以便重用

• “保存这次 Sentinel-2 搜索，以便稍后下载。”
• “列出我保存的搜索。”
• “显示我以 <slug> 名称保存的搜索内容。”
• “删除保存的搜索 <slug>。”

下载和购物车（需要登录——见下文）

• “我已登录 Bhoonidhi 吗？”
• “下载我保存的搜索 <slug> 中的开放数据场景。”
• “下载进度如何？”
• “下载 <slug>，完成后告诉我——我会继续工作。”
• “将 <slug> 中需要付费的场景加入购物车。”
• “这周我的购物车里有什么？”

登录（用于下载和购物车）

搜索、已保存的查询和预览无需凭据。下载场景和将场景暂存到购物车则需要凭据。通过其他方式登录一次——服务会重用 bhd CLI 写入的同一会话：

bhd auth login

MCP 服务绝不会将用户名或密码作为工具参数接收，auth_status 也绝不会返回你的令牌。对于没有交互式登录的无头环境，也可以在服务的环境变量中设置 BHOONIDHI_USERNAME / BHOONIDHI_PASSWORD；服务只会读取它们以建立会话。

配置

设置为环境变量（均为可选）：

变量	默认值	用途
BHOONIDHI_MCP_GEOCODER_USER_AGENT	bhoonidhi-mcp/0.3	发送给 Nominatim 的 User-Agent（其使用政策要求填写描述性内容）。
BHOONIDHI_MCP_FUZZY_THRESHOLD	88	卫星名称匹配的置信度阈值（0–100）；低于此值时，会返回候选项供 Agent 确认。
BHOONIDHI_MCP_MAX_RESULTS	50	search_scenes 内联返回的场景数量上限。
BHOONIDHI_MCP_DOWNLOAD_ROOT	~/Downloads	下载写入位置的允许列表根目录，路径格式为 <root>/<slug>/。Agent 无法选择任意路径。
BHOONIDHI_MCP_DOWNLOAD_PARALLEL	4	并行下载工作线程数。
BHOONIDHI_MCP_LARGE_DOWNLOAD_MB	500	下载的实时字节总量（或已知大小）超过此值后，状态会将其标记为大型下载，并引导 Agent 转交处理或运行独立命令。
BHOONIDHI_USERNAME / BHOONIDHI_PASSWORD	（未设置）	可选的无头登录方式。建议使用 bhd auth login；在其他渠道填写这些信息，切勿将其提交到代码库。

数据使用与署名

通过此服务访问的影像归 ISRO/NRSC 所有，并受 Bhoonidhi EULA 约束，而非本项目的 MIT 许可证约束——该许可证仅涵盖此处的代码，不涵盖其他内容。EULA 对您的要求如下：

• 使用您自己的账户。 下载和购物车操作使用您自己的 Bhoonidhi 登录信息进行身份验证，登录信息需通过其他途径获取。服务绝不会将密码作为工具参数，也绝不会共享或绕过会话。
• 注明来源。 使用这些数据发布的任何内容都必须带有说明文字 ISRO-IRS。
• 不要转售原始数据。 门户标记为开放数据的影像可免费使用、发布和用于创作。原始产品不得以原始形式进行商业再分发，但衍生产品和增值产品不受此限。
• 定价影像和需下单的影像须通过门户处理。 此服务绝不会绕过付款：定价影像和需下单的影像只会加入购物车，您需要在 Bhoonidhi 上完成订单和付款。

开发

uv sync
uv run pytest        # test suite
uv run ruff check .  # lint

许可证

MIT — 详见 LICENSE。