{
  "markdown": "# @globalfishingwatch/gfw-mcp-js\n\nAccess [Global Fishing Watch](https://globalfishingwatch.org) data from any MCP-compatible AI assistant or directly from the terminal. Search vessels, retrieve apparent fishing activity and port-visit events, look up Marine Protected Areas, Exclusive Economic Zones and RFMOs, calculate apparent fishing activity hours within any region, and compute aggregate event statistics.\n\nThis package can be used in three modes:\n\n- **MCP server (stdio)** — connect any MCP-compatible AI assistant (Claude, Cursor, Windsurf, VS Code…) to GFW data via a local process\n- **MCP server (HTTP)** — deploy as a Cloud Run service; AI clients connect via URL with no local install required\n- **CLI** — query GFW data directly from the terminal\n\n## Requirements\n\n- Node.js 18+\n- A [GFW API key](https://globalfishingwatch.org/our-apis/) — if not yet available, request one at https://globalfishingwatch.org/our-apis/tokens\n\n---\n\n## MCP Server\n\n### Quick start (no install)\n\n```bash\nGFW_TOKEN=your_gfw_api_key_here npx @globalfishingwatch/gfw-cli mcp\n```\n\n`mcp` is a subcommand of the CLI that starts the MCP stdio server.\n\n### Authentication\n\nThe MCP server resolves the API token in this order:\n\n1. `GFW_TOKEN` environment variable (compatibility alias)\n2. `API_KEY` environment variable\n3. `~/.gfw/config.json` (saved via `npx @globalfishingwatch/gfw-cli auth login`)\n\nIf you have already run `npx @globalfishingwatch/gfw-cli auth login` from the CLI, the MCP server will pick up the stored token automatically — no need to set environment variables in your client config.\n\n### Client configuration\n\n#### Claude Desktop\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n`%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@globalfishingwatch/gfw-cli\", \"mcp\"],\n      \"env\": {\n        \"GFW_TOKEN\": \"your_gfw_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Code (Plugin — recommended)\n\nFirst add the GFW marketplace, then install the plugin:\n\n```bash\n# 1. Add the GFW marketplace (one-time)\n/plugin marketplace add GlobalFishingWatch/gfw-mcp-js\n\n# 2. Install the plugin (will prompt for your GFW API token)\nclaude plugin install gfw@globalfishingwatch\n```\n\n#### Claude Code (manual MCP)\n\n```bash\nclaude mcp add gfw -- npx -y @globalfishingwatch/gfw-cli mcp\nexport GFW_TOKEN=your_gfw_api_key_here\n```\n\n#### Cursor\n\n`.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@globalfishingwatch/gfw-cli\", \"mcp\"],\n      \"env\": { \"GFW_TOKEN\": \"your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### Windsurf\n\n`~/.codeium/windsurf/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@globalfishingwatch/gfw-cli\", \"mcp\"],\n      \"env\": { \"GFW_TOKEN\": \"your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### VS Code (Copilot)\n\n`.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"gfw\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@globalfishingwatch/gfw-cli\", \"mcp\"],\n      \"env\": { \"GFW_TOKEN\": \"your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### OpenClaw\n\n`~/.openclaw/openclaw.json`\n\n```json\n{\n  \"tools\": {\n    \"mcp\": {\n      \"servers\": {\n        \"gfw\": {\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@globalfishingwatch/gfw-cli\", \"mcp\"],\n          \"env\": { \"GFW_TOKEN\": \"your_gfw_api_key_here\" }\n        }\n      }\n    }\n  }\n}\n```\n\n#### Gemini CLI\n\nOne-line install (Gemini Extensions):\n\n```bash\ngemini extensions install https://github.com/GlobalFishingWatch/gfw-mcp-js\nexport GFW_TOKEN=your_gfw_api_key_here\n```\n\nThis installs the MCP server, the agent instructions ([SKILL.md](SKILL.md)), and registers the extension automatically.\n\nManual config alternative — `~/.gemini/settings.json` (global) or `.gemini/settings.json` (per project):\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@globalfishingwatch/gfw-cli\", \"mcp\"],\n      \"env\": { \"GFW_TOKEN\": \"your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### Claude Code (Skill only)\n\nIf you want the agent guidelines without the plugin, the repo ships a [SKILL.md](SKILL.md) at the root.\n\nInstall via [skills.sh](https://skills.sh) CLI:\n\n```bash\nnpx skills add GlobalFishingWatch/gfw-mcp-js\n```\n\nOr clone directly into your Claude skills directory:\n\n```bash\ngit clone https://github.com/GlobalFishingWatch/gfw-mcp-js ~/.claude/skills/gfw-mcp-js\n```\n\nClaude Code auto-discovers `SKILL.md` and loads the agent guidelines plus tool reference. Pair with the MCP server config above (`claude mcp add gfw -- npx -y @globalfishingwatch/gfw-cli mcp`) so the skill's tool documentation matches the live MCP tools.\n\n### Alternative: local clone\n\n```bash\ngit clone https://github.com/globalfishingwatch/gfw-mcp-js\ncd gfw-mcp-js\nnpm install && npm run build\n```\n\nThen replace `npx -y @globalfishingwatch/gfw-cli` with `node /absolute/path/to/gfw-mcp-js/dist/bin.js` in any config above.\n\n### Available MCP tools\n\n| Tool                  | Description                                                                                                                                                                                                      |\n| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `vessel-search`       | Search vessels by name, MMSI, IMO, callsign, flag, owner, or gear type. To avoid misinterpretation, please check data caveats [here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information) and for more details refer to [GFW Vessel API](https://globalfishingwatch.org/our-apis/documentation#vessels-api). |\n| `vessel-by-id`        | Fetch full vessel profile(s) by GFW vessel ID(s); returns metadata, registry owners, a map URL, and `relatedIdentities` (other AIS identities linked to the same physical vessel) |\n| `vessel-events`       | Retrieve apparent fishing, encounter, port visit, or loitering events; filter by vessel, region, date, confidence, and encounter type. To avoid misinterpretation, please check data caveats [here](https://globalfishingwatch.org/our-apis/documentation#how-are-the-events-estimated) and for more details refer to [GFW Events API](https://globalfishingwatch.org/our-apis/documentation#events-api) |\n| `events-stats`        | Compute aggregate statistics (total events, unique vessels, flag breakdown) over a date range, optionally filtered by region and grouped by flag or gear type; returns a GFW map URL (except for fishing events). For more details check [Stats API](https://globalfishingwatch.org/our-apis/documentation#statistics-on-fishing-activity-worldwide) |\n| `region-id-lookup`    | Resolve MPA, EEZ, or RFMO names to canonical region IDs. To check the sources of the regions, please check [here](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition) |\n| `region-geometry-url` | Get the URL to fetch the GeoJSON geometry of a specific MPA, EEZ, or RFMO |\n| `area-report`         | Calculate apparent fishing, SAR, Sentinel-2, or AIS presence hours worldwide (`regionWorld: true`) or in a specific region (MPA, EEZ, RFMO); optional flag, gear type, vessel type, and speed filters; supports groupBy flag/geartype. To avoid misinterpretations please check data caveats about [AIS presence here](https://globalfishingwatch.org/our-apis/documentation#ais-vessel-presence-caveats) and about [SAR Vessel Detections here](https://globalfishingwatch.org/our-apis/documentation#sar-vessel-detections-data-caveats) |\n| `vessel-insights`     | Retrieve apparent fishing activity, AIS off event, AIS coverage, and IUU vessel list insights for one or more vessels over a date range; returns a GFW map URL per vessel. To avoid misinterpretation, review [data caveats here](https://globalfishingwatch.org/our-apis/documentation#insights-api-fishing-detected-in-no-take-mpas). For more details refer to [GFW Insights API](https://globalfishingwatch.org/our-apis/documentation#insights-api) |\n\n---\n\n## Remote MCP Server (Cloud Run)\n\nDeploy as an HTTP service so AI clients connect via URL — no local Node.js install required on the client side. Each client passes its own GFW API token as a Bearer header; the server forwards it to the GFW API transparently.\n\n### Deploy to Cloud Run\n\n```bash\n# Build and push image\ngcloud builds submit --tag gcr.io/YOUR_PROJECT/gfw-mcp .\n\n# Deploy\ngcloud run deploy gfw-mcp \\\n  --image gcr.io/YOUR_PROJECT/gfw-mcp \\\n  --platform managed \\\n  --region us-central1 \\\n  --allow-unauthenticated \\\n  --port 8080\n```\n\nNo secrets needed in the deployment — clients supply their own GFW token per request.\n\n### Client configuration\n\nThe client sends its GFW API token as `Authorization: Bearer <token>`. The server uses it to call the GFW API on behalf of the client.\n\n#### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"url\": \"https://mcp.globalfishingwatch.org/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### Claude Code\n\n```bash\nclaude mcp add --transport http gfw https://mcp.globalfishingwatch.org/mcp \\\n  --header \"Authorization: Bearer your_gfw_api_key_here\"\n```\n\n#### Cursor\n\n`.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"url\": \"https://mcp.globalfishingwatch.org/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### Windsurf\n\n`~/.codeium/windsurf/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"gfw\": {\n      \"url\": \"https://mcp.globalfishingwatch.org/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n#### VS Code (Copilot)\n\n`.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"gfw\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.globalfishingwatch.org/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer your_gfw_api_key_here\" }\n    }\n  }\n}\n```\n\n### Health check\n\n```bash\ncurl https://mcp.globalfishingwatch.org/health\n# {\"status\":\"ok\"}\n```\n\n### stdio vs HTTP comparison\n\n| | stdio (local) | HTTP (Cloud Run) |\n|---|---|---|\n| Install required | Node.js 18+ | None |\n| Token location | `GFW_TOKEN` env var or `auth login` | `Authorization` header per request |\n| Multi-user | No | Yes |\n| Command | `gfw mcp` | `gfw mcp-server` |\n\n---\n\n## CLI\n\n### Install\n\n```bash\n# Run without installing\nnpx @globalfishingwatch/gfw-cli --help\n\n# Or install globally\nnpm install -g @globalfishingwatch/gfw-cli\nnpx @globalfishingwatch/gfw-cli --help\n```\n\n### Authentication\n\nToken resolution order:\n\n1. `GFW_TOKEN` environment variable\n2. `API_KEY` environment variable (compatibility alias)\n3. `~/.gfw/config.json` (saved via `auth login`)\n\n```bash\n# Save token interactively (stored in ~/.gfw/config.json)\nnpx @globalfishingwatch/gfw-cli auth login\n\n# Check which token source is active\nnpx @globalfishingwatch/gfw-cli auth status\n\n# Remove stored token\nnpx @globalfishingwatch/gfw-cli auth logout\n```\n\nOr pass the token inline for a single command:\n\n```bash\nGFW_TOKEN=your_key npx @globalfishingwatch/gfw-cli vessel-search --name \"Maria\"\n```\n\n### Commands\n\n#### `vessel-search`\n\nSearch vessels by name, MMSI, IMO, callsign, flag, owner, or activity date range.\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-search [--name <name>] [--mmsi <mmsi>] [--imo <imo>]\n  [--callsign <cs>] [--flag <ISO3>] [--owner <owner>]\n  [--active-from <YYYY-MM-DD>] [--active-to <YYYY-MM-DD>] [--limit <n>]\n```\n\nAt least one filter must be provided.\n\n| Parameter                       | Format / values                                    |\n| ------------------------------- | -------------------------------------------------- |\n| `--mmsi`                        | 9-digit string                                     |\n| `--imo`                         | 7-digit string                                     |\n| `--flag`                        | ISO 3166-1 alpha-3 code (e.g. `ESP`, `CHN`, `USA`) |\n| `--owner`                       | Owner name or partial name (wildcard match)        |\n| `--active-from` / `--active-to` | `YYYY-MM-DD`                                       |\n| `--limit`                       | 1–50 (default 10)                                  |\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-search --name \"Maria\" --flag CHN\nnpx @globalfishingwatch/gfw-cli vessel-search --mmsi 123456789\nnpx @globalfishingwatch/gfw-cli vessel-search --flag ESP --active-from 2024-01-01 --active-to 2024-12-31 --limit 20\n```\n\n#### `vessel-by-id`\n\nFetch full vessel profile(s) by GFW vessel ID.\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-by-id --ids <id> [<id2> ...]\n```\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-by-id --ids abc123\nnpx @globalfishingwatch/gfw-cli vessel-by-id --ids abc123 def456 ghi789\n```\n\nEach result includes `relatedIdentities` — an array of other AIS identities linked to the same physical vessel (different MMSI or name/flag periods), each with its own `mapUrl`. Empty array if none.\n\n#### `vessel-events`\n\nRetrieve fishing, encounter, port visit, or loitering events.\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-events --event-type <type>\n  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>\n  [--vessel-id <id>] [--limit <n>] [--offset <n>]\n  [--confidence <2|3|4> ...]          # port_visit only\n  [--encounter-types <type> ...]      # encounter only\n  [--region-type <MPA|EEZ|RFMO>] [--region-id <id>]\n```\n\n| Parameter                     | Format / values                                                                                                                                                 |\n| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--event-type`                | `fishing` \\| `encounter` \\| `port_visit` \\| `loitering`                                                                                                         |\n| `--start-date` / `--end-date` | `YYYY-MM-DD`                                                                                                                                                    |\n| `--limit`                     | 1–100 (default 20)                                                                                                                                              |\n| `--confidence`                | `2`, `3`, `4` (one or more; port_visit only; default `4`)                                                                                                       |\n| `--encounter-types`           | `CARRIER-FISHING` \\| `CARRIER-BUNKER` \\| `FISHING-BUNKER` \\| `FISHING-FISHING` \\| `SUPPORT-FISHING` (encounter only; default `CARRIER-FISHING SUPPORT-FISHING`) |\n| `--region-type`               | `MPA` \\| `EEZ` \\| `RFMO`                                                                                                                                        |\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-events --event-type fishing --start-date 2024-01-01 --end-date 2024-06-01\nnpx @globalfishingwatch/gfw-cli vessel-events --event-type port_visit --vessel-id abc123 --start-date 2024-01-01 --end-date 2024-12-31\nnpx @globalfishingwatch/gfw-cli vessel-events --event-type encounter --start-date 2024-01-01 --end-date 2024-12-31 --encounter-types CARRIER-FISHING SUPPORT-FISHING\nnpx @globalfishingwatch/gfw-cli vessel-events --event-type fishing --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-06-01\n```\n\n#### `events-stats`\n\nCompute aggregate event statistics over a date range.\n\n```bash\nnpx @globalfishingwatch/gfw-cli events-stats --event-type <type>\n  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>\n  [--group-by <FLAG|GEARTYPE>]\n  [--region-type <MPA|EEZ|RFMO>] [--region-id <id>]\n  [--confidence <levels> ...] [--encounter-types <types> ...]\n```\n\n| Parameter                     | Format / values                                                                                                                                                 |\n| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--event-type`                | `fishing` \\| `encounter` \\| `port_visit` \\| `loitering`                                                                                                         |\n| `--start-date` / `--end-date` | `YYYY-MM-DD`                                                                                                                                                    |\n| `--group-by`                  | `FLAG` \\| `GEARTYPE` (default `FLAG`)                                                                                                                           |\n| `--region-type`               | `MPA` \\| `EEZ` \\| `RFMO`                                                                                                                                        |\n| `--confidence`                | `2`, `3`, `4` (one or more; port_visit only; default `4`)                                                                                                       |\n| `--encounter-types`           | `CARRIER-FISHING` \\| `CARRIER-BUNKER` \\| `FISHING-BUNKER` \\| `FISHING-FISHING` \\| `SUPPORT-FISHING` (encounter only; default `CARRIER-FISHING SUPPORT-FISHING`) |\n\n```bash\nnpx @globalfishingwatch/gfw-cli events-stats --event-type fishing --start-date 2024-01-01 --end-date 2024-12-31\nnpx @globalfishingwatch/gfw-cli events-stats --event-type fishing --start-date 2024-01-01 --end-date 2024-12-31 --group-by GEARTYPE\nnpx @globalfishingwatch/gfw-cli events-stats --event-type encounter --start-date 2024-01-01 --end-date 2024-12-31 --region-type RFMO --region-id WCPFC\n```\n\n**Returns:** `{ flags[], numEvents, numFlags, numVessels, groups[], mapUrl, dataCaveats? }` — `groups` contains `{ name, value }` pairs sorted descending by count. `mapUrl` links to the GFW map to visualise the queried events; it is **not present** when `--event-type` is `fishing`. `dataCaveats` is an array of markdown strings present when `--event-type` is `fishing` — always display every item.\n\n#### `region-id-lookup`\n\nResolve an MPA, EEZ, or RFMO name to its canonical ID.\n\n```bash\nnpx @globalfishingwatch/gfw-cli region-id-lookup --region-type <MPA|EEZ|RFMO> --query <name> [--limit <n>]\n```\n\nUse this before `area-report` or `vessel-events` when you only know the human-readable name of a region.\n\n| Parameter       | Format / values          |\n| --------------- | ------------------------ |\n| `--region-type` | `MPA` \\| `EEZ` \\| `RFMO` |\n| `--limit`       | 1–20 (default 5)         |\n\n```bash\nnpx @globalfishingwatch/gfw-cli region-id-lookup --region-type MPA --query \"Galapagos\"\nnpx @globalfishingwatch/gfw-cli region-id-lookup --region-type EEZ --query \"Patagonia\" --limit 10\nnpx @globalfishingwatch/gfw-cli region-id-lookup --region-type RFMO --query \"WCPFC\"\n```\n\n#### `region-geometry-url`\n\nGet the GeoJSON URL for a specific region (no API token required).\n\n```bash\nnpx @globalfishingwatch/gfw-cli region-geometry-url --region-type <MPA|EEZ|RFMO> --id <id>\n```\n\n| Parameter       | Format / values          |\n| --------------- | ------------------------ |\n| `--region-type` | `MPA` \\| `EEZ` \\| `RFMO` |\n\n```bash\nnpx @globalfishingwatch/gfw-cli region-geometry-url --region-type EEZ --id 8386\nnpx @globalfishingwatch/gfw-cli region-geometry-url --region-type MPA --id 12345\n```\n\n#### `area-report`\n\nCalculate fishing, SAR, Sentinel-2, or AIS presence hours inside a region or worldwide. Date range must not exceed 1 year.\n\n> **Important:** This command must never be run in parallel. If multiple reports are needed, run them sequentially — one at a time, waiting for each to complete before starting the next.\n\n```bash\n# Region-specific report\nnpx @globalfishingwatch/gfw-cli area-report --region-type <MPA|EEZ|RFMO> --region-id <id>\n  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>\n  [--type <FISHING|PRESENCE|SAR|SENTINEL2>]\n  [--flags <ISO3> ...]\n  [--geartypes <type> ...]    # FISHING/SAR/SENTINEL2 only\n  [--vessel-types <type> ...] # PRESENCE only\n  [--speeds <range> ...]      # PRESENCE only\n  [--group-by <VESSEL_ID|FLAG|GEARTYPE|FLAGANDGEARTYPE>]\n  [--top-vessels-limit <n>]   # VESSEL_ID group-by only (default 10)\n\n# World report (mutually exclusive with --region-type / --region-id)\nnpx @globalfishingwatch/gfw-cli area-report --region-world\n  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>\n  [--type <FISHING|PRESENCE|SAR|SENTINEL2>]\n  [--flags <ISO3> ...] [--geartypes <type> ...] [--group-by <...>]\n```\n\n| Parameter                     | Format / values                                                                                                                                                                                                                                                                                                                                                |\n| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--region-world`              | Boolean flag. Run the report for the entire world. Mutually exclusive with `--region-type` and `--region-id`.                                                                                                                                                                                                                                                  |\n| `--region-type`               | `MPA` \\| `EEZ` \\| `RFMO`. Required when `--region-world` is not set.                                                                                                                                                                                                                                                                                           |\n| `--region-id`                 | Canonical region ID. Required when `--region-world` is not set.                                                                                                                                                                                                                                                                                                |\n| `--start-date` / `--end-date` | `YYYY-MM-DD` (max range: 1 year)                                                                                                                                                                                                                                                                                                                               |\n| `--type`                      | `FISHING` (default) \\| `PRESENCE` \\| `SAR` \\| `SENTINEL2` — `FISHING`: AIS-based fishing effort hours; `PRESENCE`: AIS vessel presence hours regardless of activity; `SAR`: Synthetic Aperture Radar vessel detection hours (satellite radar, independent of AIS); `SENTINEL2`: Sentinel-2 optical satellite imagery vessel detection hours                    |\n| `--flags`                     | ISO 3166-1 alpha-3 codes (e.g. `ESP`, `CHN`); up to 10                                                                                                                                                                                                                                                                                                         |\n| `--geartypes`                 | `tuna_purse_seines` \\| `driftnets` \\| `trollers` \\| `set_longlines` \\| `purse_seines` \\| `pots_and_traps` \\| `other_fishing` \\| `dredge_fishing` \\| `set_gillnets` \\| `fixed_gear` \\| `trawlers` \\| `fishing` \\| `seiners` \\| `other_purse_seines` \\| `other_seines` \\| `squid_jigger` \\| `pole_and_line` \\| `drifting_longlines` (FISHING/SAR/SENTINEL2 only) |\n| `--vessel-types`              | `carrier` \\| `seismic_vessel` \\| `passenger` \\| `other` \\| `support` \\| `bunker` \\| `gear` \\| `cargo` \\| `fishing` \\| `discrepancy` (PRESENCE only)                                                                                                                                                                                                            |\n| `--speeds`                    | `2-4` \\| `4-6` \\| `6-10` \\| `10-15` \\| `15-25` \\| `>25` (PRESENCE only)                                                                                                                                                                                                                                                                                        |\n| `--group-by`                  | `VESSEL_ID` (default) \\| `FLAG` \\| `GEARTYPE` \\| `FLAGANDGEARTYPE` (`GEARTYPE`/`FLAGANDGEARTYPE` only valid with `--type FISHING`, `SAR`, or `SENTINEL2`)                                                                                                                                                                                                      |\n| `--top-vessels-limit`         | Integer 1–100; default `10`. Number of top vessels to return when `--group-by VESSEL_ID`. Ignored for other group-by values.                                                                                                                                                                                                                                   |\n\n```bash\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31\nnpx @globalfishingwatch/gfw-cli area-report --region-type MPA --region-id 12345 --start-date 2024-01-01 --end-date 2024-12-31 --flags CHN ESP\nnpx @globalfishingwatch/gfw-cli area-report --region-type RFMO --region-id WCPFC --start-date 2024-01-01 --end-date 2024-12-31 --type FISHING --group-by FLAG\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type PRESENCE --vessel-types fishing cargo\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type SAR\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type SENTINEL2\nnpx @globalfishingwatch/gfw-cli area-report --region-world --start-date 2024-01-01 --end-date 2024-12-31 --type FISHING --group-by FLAG\n```\n\n**Returns:** `{ regionType, regionId, dateRange, gfwMapUrl }` for region reports, or `{ regionWorld: true, dateRange, gfwMapUrl }` for world reports, plus one activity value field:\n\n- `fishingHours` — total fishing hours (present when `--type FISHING`)\n- `presenceHours` — total vessel presence hours (present when `--type PRESENCE`)\n- `detections` — total SAR or Sentinel-2 vessel detections (present when `--type SAR` or `--type SENTINEL2`)\n\nAnd optionally:\n\n- `topVessels` — top N vessels sorted descending by activity (N = `--top-vessels-limit`, default 10), each with `vesselId`, `shipName`, `mmsi`, `flag`, `geartype`, and `value` (hours for FISHING/PRESENCE; detections for SAR/SENTINEL2). Only present when `--group-by VESSEL_ID`.\n- `rows` — aggregated entries sorted descending by activity value, each containing the grouping fields plus `hours`. Only present when `--group-by FLAG`, `GEARTYPE`, or `FLAGANDGEARTYPE`.\n- `dataCaveats` — array of markdown strings with data caveats (present when caveats exist for the requested type). Always display every item in this array to the user.\n- Applied filters (`flags`, `vesselTypes`, `speeds`, `geartypes`) echoed back when provided.\n\n#### `vessel-insights`\n\nRetrieve insights for one or more vessels over a date range.\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-insights --vessel-ids <id> [<id2> ...]\n  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>\n  --includes <FISHING|GAP|COVERAGE|VESSEL-IDENTITY-IUU-VESSEL-LIST> [...]\n```\n\n| Parameter      | Format / values                                                                                                                                                                                                                                                     |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--vessel-ids` | One or more GFW vessel IDs                                                                                                                                                                                                                                          |\n| `--start-date` | `YYYY-MM-DD`                                                                                                                                                                                                                                                        |\n| `--end-date`   | `YYYY-MM-DD`                                                                                                                                                                                                                                                        |\n| `--includes`   | `FISHING` \\| `GAP` \\| `COVERAGE` \\| `VESSEL-IDENTITY-IUU-VESSEL-LIST` — one or more; `FISHING`: apparent fishing events and RFMO/MPA violations; `GAP`: AIS-off dark activity; `COVERAGE`: AIS reception %; `VESSEL-IDENTITY-IUU-VESSEL-LIST`: IUU list appearances |\n\n**Returns:** `{ period, vesselIdsWithoutIdentity, mapUrls, apparentFishing?, gap?, coverage?, vesselIdentity?, dataCaveats? }` — only insight fields for requested types are present. `mapUrls` is an object keyed by vessel ID linking each vessel to its GFW map profile for the queried period — always show these URLs to the user in full. `dataCaveats` is an array of markdown strings present when `--includes FISHING` — always display every item.\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-insights --vessel-ids abc123 --start-date 2024-01-01 --end-date 2024-12-31 --includes FISHING GAP\nnpx @globalfishingwatch/gfw-cli vessel-insights --vessel-ids abc123 def456 --start-date 2024-01-01 --end-date 2024-12-31 --includes FISHING GAP COVERAGE VESSEL-IDENTITY-IUU-VESSEL-LIST\n```\n\n#### `screenshot`\n\nGenerate a screenshot of a GFW map URL. Requires `playwright` and Chromium — install once if not already present:\n\n```bash\nnpm install playwright && npx playwright install chromium\n```\n\n```bash\nnode scripts/screenshot_gfw.js <url> <output_path>\n```\n\n| Argument        | Description                                                                  |\n| --------------- | ---------------------------------------------------------------------------- |\n| `<url>`         | The full GFW map URL (e.g. a `mapUrl` or `gfwMapUrl` from any tool response) |\n| `<output_path>` | Destination path for the PNG file (e.g. `/tmp/gfw_vessel_abc123.png`)        |\n\nThe script appends `&screenshotMode=true` to the URL, waits for network and JS idle, then saves a 1280×800 PNG. Respects `https_proxy` / `HTTPS_PROXY` / `http_proxy` / `HTTP_PROXY` environment variables.\n\n```bash\nnode scripts/screenshot_gfw.js \"https://globalfishingwatch.org/map/vessel/abc123\" /tmp/gfw_vessel_abc123.png\n```\n\n---\n\n### Output\n\nAll commands output JSON to stdout, ready to pipe to `jq`:\n\n```bash\nnpx @globalfishingwatch/gfw-cli vessel-search --name \"Maria\" | jq '.results[].name'\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 | jq '.fishingHours'\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type PRESENCE | jq '.presenceHours'\nnpx @globalfishingwatch/gfw-cli area-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type SAR | jq '.detections'\n```\n\n---\n\n## Environment variables\n\n| Variable    | Default       | Description                                            |\n| ----------- | ------------- | ------------------------------------------------------ |\n| `GFW_TOKEN` | —             | GFW API bearer token                            |\n| `API_KEY`   | —             | Alias for `GFW_TOKEN` (backwards compatibility) |\n| `NODE_ENV`  | `development` | Environment name sent to Sentry                 |\n\n---\n\n## Project structure\n\n```\nbin.ts              # Entry point: loads CLI (dist/bin.js registered as \"mcp\" binary)\nindex.ts            # MCP server stdio setup (used by the `mcp` CLI command)\nmcp-server.ts       # McpServer creation and tool registration\ncli/\n  index.ts          # CLI entry point (commander); includes the `mcp` subcommand\n  auth.ts           # Token resolution and auth commands\nmiddleware/\n  auth.ts           # Bearer / X-API-Key authentication middleware\ntools/              # One file per tool; each exports register() + a pure handler\nlib/\n  api.ts            # gfwFetch() — GFW API client\n  response.ts       # createToolResponse() / createErrorResponse()\n  types.ts          # Shared TypeScript types and dataset constants\n```\n",
  "bytes": 33741,
  "sha": "a0b812445af6ac0e7be87698b0b43945d25c331e16a2a2e19fbd8781d614a26c",
  "repo_slug": "globalfishingwatch/gfw-mcp-js",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_globalfishingwatch_gfw_mcp_js_7d4ceae2/readme"
}