{
  "markdown": "# bhoonidhi-mcp\n\n<!-- mcp-name: io.github.geovicco-dev/bhoonidhi-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/bhoonidhi-mcp.svg)](https://pypi.org/project/bhoonidhi-mcp/)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.geovicco-dev/bhoonidhi-mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nAn [MCP](https://modelcontextprotocol.io) server that lets an AI agent search,\nsave, download, and cart satellite scenes from [ISRO's Bhoonidhi Browse & Order portal](https://bhoonidhi.nrsc.gov.in/)\n(NRSC) in natural language. An agent can turn a sentence like \"Sentinel-2 over\nShillong last January\" into a real search against the live portal, see honestly\nwhat is available to download, save a search to reuse later, preview what a\ndownload would fetch, and — once logged in — download open-access scenes or\nstage them to the cart.\n\nIt is a thin adapter over the\n[`bhoonidhi-downloader`](https://github.com/geovicco-dev/bhoonidhi-downloader)\nSDK — the same client the `bhd` CLI uses — so no portal logic is duplicated.\n\n## Status\n\n**Search and save with no login; download and cart with one.** The tools reach\nthe full archive of 41 satellite missions and 79 sensors, search the live\nportal, and save searches to reusable slugs — all without credentials.\nDownloading open-access scenes and staging scenes to the Bhoonidhi cart need a\nlogin, done out of band with `bhd auth login` (the server reuses that session).\n\n## Tools\n\n| Tool | What it does | Login |\n| ------ | -------------- | ------- |\n| `list_archive` | The vocabulary of satellites, sensors, and search tokens the portal supports, live from Bhoonidhi. | no |\n| `resolve_location` | Turns a place name (\"Loktak Lake\") into a centroid and bounding box. Rejects inputs that are not place names. | no |\n| `search_scenes` | Natural-language scene search over an area and date range. Resolves a casual satellite name to exact tokens, and reports each scene's availability (Ready / Archived / OnOrder / Priced). Stateless — nothing is saved. | no |\n| `preview_download` | A dry run: shows what downloading the results would fetch, and what would be skipped, before anything is downloaded. | no |\n| `save_query` | Persists a search (same arguments as `search_scenes`) to a reusable slug, so it can be downloaded or staged to the cart later. | no |\n| `list_queries` | Lists saved queries as compact summaries: slug, name, date range, satellites, area, and availability. | no |\n| `show_query` | Returns one saved query by slug, with its scenes. | no |\n| `remove_query` | Deletes a saved query by slug. | no |\n| `auth_status` | Reports whether a login is configured. Never handles a password or token. | no |\n| `download_query` | Downloads a saved query's open-access scenes in the background, to a fixed server-configured root. Returns a `job_id` at once. | yes |\n| `download_status` | One-off check of a background download by `job_id`: bytes downloaded, transfer rate, percent when the size is known, and per-scene detail. | no |\n| `download_wait` | Blocks until a download finishes (or a capped timeout), then reports — the efficient primitive a background watcher loops on. | no |\n| `cart_add` | Stages a saved query's scenes to the cart (routes each to ready / on-order / priced). | yes |\n| `cart_list` | Lists scenes currently staged in the cart. | yes |\n| `cart_remove` | Removes scenes from the cart. | yes |\n\nAvailability matters: an `OpenData` scene is not necessarily staged for\ndownload. `search_scenes` and `preview_download` distinguish **Ready** (fetch it\nnow) from **Archived** (open data, but may need a request on the portal first),\nso an agent does not over-promise.\n\nDownloads run in the background, independent of the conversation:\n`download_query` returns a `job_id` at once and the transfer proceeds on its own.\nCheck progress once with `download_status` — it reports bytes downloaded, a\ntransfer rate, and a percent once the size is known — or follow a job to\ncompletion with `download_wait`, which blocks until it finishes (or a capped\ntimeout) so an agent can delegate a background watcher and keep the conversation\nfree instead of sleep-looping. A job lives only as long as the server process,\nso once a download proves large the status recommends running a standalone `bhd\nquery download <slug>` command you own instead.\n\n## Install\n\nThe server is a Python package with a console entry point, `bhoonidhi-mcp`. The\nsimplest way to run it is with [uv](https://docs.astral.sh/uv/) — `uvx` fetches,\nbuilds, and launches it straight from the source, no clone or virtualenv needed:\n\n```bash\nuvx --from git+https://github.com/geovicco-dev/bhoonidhi-mcp bhoonidhi-mcp\n```\n\nThe first run builds from source; later runs start from cache. The server speaks\nstdio and is launched by an MCP client — you point the client at that command.\n\nPrefer a local checkout (for development)? Clone and `uv sync`, then use\n`.venv/bin/bhoonidhi-mcp` as the command instead:\n\n```bash\ngit clone https://github.com/geovicco-dev/bhoonidhi-mcp\ncd bhoonidhi-mcp\nuv sync\n```\n\n## Connecting a client\n\nEvery MCP client needs the same thing: the command to launch. Point it at `uvx`\nwith the source and entry point as arguments.\n\n### Claude Desktop / Claude Code\n\n`claude_desktop_config.json` (or `claude mcp add`):\n\n```json\n{\n  \"mcpServers\": {\n    \"bhoonidhi\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/geovicco-dev/bhoonidhi-mcp\", \"bhoonidhi-mcp\"]\n    }\n  }\n}\n```\n\n### OpenCode\n\n`~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"bhoonidhi\": {\n      \"type\": \"local\",\n      \"command\": [\"uvx\", \"--from\", \"git+https://github.com/geovicco-dev/bhoonidhi-mcp\", \"bhoonidhi-mcp\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### MCP Inspector (to try it without an agent)\n\n```bash\nnpx @modelcontextprotocol/inspector uvx --from git+https://github.com/geovicco-dev/bhoonidhi-mcp bhoonidhi-mcp\n```\n\n## Example\n\nAsk an agent, in plain language:\n\n> \"What Sentinel-2 scenes are over Shillong in January 2024, and how many can I\n> actually download?\"\n\nThe agent calls `resolve_location` for Shillong, then `search_scenes`, and\nanswers from the result — for example, that all scenes are *Archived* (open\ndata, but each may need a request on the portal before it will download), rather\nthan claiming they are all ready.\n\n## Prompts to try\n\nCopy these into any connected agent to get a feel for what it can do.\n\n### Discover the archive\n\n- \"What satellites and sensors does Bhoonidhi have?\"\n- \"Which sensors does ResourceSat-2A carry, and at what resolution?\"\n- \"Does Bhoonidhi have any radar satellites?\"\n\n### Search for scenes\n\n- \"Find Sentinel-2 scenes over Shillong in January 2024.\"\n- \"Show me Cartosat imagery within 20 km of Bengaluru in the first half of 2024.\"\n- \"Any Sentinel-1 scenes over the Sundarbans in March 2024?\"\n- \"What Landsat-8 imagery covers Kaziranga National Park last winter?\"\n- \"Find MODIS scenes over the Rann of Kutch in December 2023.\"\n\n### Check what's available to download\n\n- \"Of those Sentinel-2 scenes, how many can I actually download right now?\"\n- \"Which of these need to be ordered or paid for?\"\n\n### Preview a download\n\n- \"Preview what downloading those scenes would fetch.\"\n\n### Save a search to reuse\n\n- \"Save that Sentinel-2 search so I can download it later.\"\n- \"List my saved searches.\"\n- \"Show me what's in the search I saved as `<slug>`.\"\n- \"Delete the saved search `<slug>`.\"\n\n### Download and cart (needs a login — see below)\n\n- \"Am I logged in to Bhoonidhi?\"\n- \"Download the open-data scenes from my saved search `<slug>`.\"\n- \"How's that download going?\"\n- \"Download `<slug>` and let me know when it's done — I'll keep working.\"\n- \"Add the priced scenes from `<slug>` to my cart.\"\n- \"What's in my cart this week?\"\n\n## Login (for downloads and cart)\n\nSearch, saved queries, and previews need no credentials. Downloading scenes and\nstaging them to the cart do. Log in once, out of band — the server reuses the\nsame session the `bhd` CLI writes:\n\n```bash\nbhd auth login\n```\n\nThe MCP server never takes a username or password as a tool argument, and\n`auth_status` never returns your token. For a headless setup with no interactive\nlogin, you can instead set `BHOONIDHI_USERNAME` / `BHOONIDHI_PASSWORD` in the\nserver's environment; the server reads them only to establish a session.\n\n## Configuration\n\nSet as environment variables (all optional):\n\n| Variable | Default | Purpose |\n| ---------- | --------- | --------- |\n| `BHOONIDHI_MCP_GEOCODER_USER_AGENT` | `bhoonidhi-mcp/0.3` | User-Agent sent to Nominatim (its usage policy asks for a descriptive one). |\n| `BHOONIDHI_MCP_FUZZY_THRESHOLD` | `88` | Score (0–100) a satellite-name match must clear to be confident; below it, candidates are returned for the agent to confirm. |\n| `BHOONIDHI_MCP_MAX_RESULTS` | `50` | Maximum scenes returned inline by `search_scenes`. |\n| `BHOONIDHI_MCP_DOWNLOAD_ROOT` | `~/Downloads` | Allow-listed root every download writes under, as `<root>/<slug>/`. The agent cannot choose an arbitrary path. |\n| `BHOONIDHI_MCP_DOWNLOAD_PARALLEL` | `4` | Parallel download workers. |\n| `BHOONIDHI_MCP_LARGE_DOWNLOAD_MB` | `500` | Once a download's live byte total (or known size) passes this, the status flags it large and steers the agent to hand off or run a standalone command. |\n| `BHOONIDHI_USERNAME` / `BHOONIDHI_PASSWORD` | *(unset)* | Optional headless login. Prefer `bhd auth login`; fill these out of band, never commit them. |\n\n## Data usage and attribution\n\nThe imagery reached through this server belongs to ISRO/NRSC and is governed by the [Bhoonidhi EULA](https://bhoonidhi.nrsc.gov.in/bhoonidhi/htmls/TnC.html), not by this project's MIT license — that license covers the code here, nothing else. What the EULA asks of you:\n\n- **Use your own account.** Downloads and cart actions authenticate with your own Bhoonidhi login, established out of band. The server never takes a password as a tool argument and never shares or bypasses a session.\n- **Credit the source.** Anything you publish from this data must carry the caption **ISRO-IRS**.\n- **Don't resell the raw data.** Scenes the portal marks as open data are free to use, publish, and build on. The original products just can't be redistributed commercially in their original form — derived and value-added products are fine.\n- **Priced and on-order scenes go through the portal.** This server never bypasses payment: priced and on-order scenes are only staged to the cart, and you complete any order and payment on Bhoonidhi.\n\n## Development\n\n```bash\nuv sync\nuv run pytest        # test suite\nuv run ruff check .  # lint\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 10752,
  "sha": "a1f58181d8985972efdc26663efbe96f996d177f87d585dd1680076b1bc2f07d",
  "repo_slug": "geovicco-dev/bhoonidhi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_geovicco_dev_bhoonidhi_mcp_0348e0ed/readme"
}