Google Images CLI and MCP — FlashData

Find diagrams or reference images, then filter by returned dimensions before reviewing the original source pages. This helps research; it does not download the images or establish reuse rights.

@flashdata-dev/google-images exposes google_images and the supporting reads for that task. It runs locally and calls the FlashData API. Node.js 22.18 or newer and a FlashData API key with this source enabled are required.

Inputs, outputs and source documentation · Get an API key · Current API pricing

The MIT software is free to install. FlashData API data calls are paid and consume Credits. Pricing and job reads are free. MCP client/model fees are separate.

Run with npx

Set FLASHDATA_API_KEY in your shell environment or secret manager. Keep the real value out of chat, committed files and command arguments. These first checks do not submit a data query:

npx --yes @flashdata-dev/[email protected] --help
npx --yes @flashdata-dev/[email protected] tools
npx --yes @flashdata-dev/[email protected] call get_pricing

Save the following as query.json. It uses flat tool arguments; no REST params wrapper is needed.

{
  "query": "solar panel diagram",
  "num": 20
}

This command performs one paid data request and writes its response to a file:

npx --yes @flashdata-dev/[email protected] call google_images --input query.json > result.json

Use --input - to read JSON from stdin. For a local project installation, run npm install @flashdata-dev/[email protected] and use npx flashdata-google-images with the same arguments.

Build an image reference inventory

The CLI returns {"ok":true,"tool":"...","result":...}. Check ok and the API/job status before consuming data. Use Python 3.10 or newer; only the standard library is needed. Save this as process-result.py beside result.json and run python3 process-result.py (Windows: py -3 process-result.py). The script reads the saved CLI response; it makes no API call. Missing optional fields in JSON summaries are represented as null:

import json
from pathlib import Path

response = json.loads(Path("result.json").read_text(encoding="utf-8"))
if not response.get("ok"):
    raise SystemExit("The request failed; inspect the response before retrying.")
result = response["result"]
if "job" in result:
    status = result["job"]["status"]
    if status != "completed":
        raise SystemExit(f"Job status: {status}. Inspect this job; do not resubmit.")
    result = result["output"]
if result.get("status") not in (None, "done"):
    raise SystemExit("No completed data yet. Read the existing job before processing.")
if not result.get("results"):
    raise SystemExit("No result record was returned.")
data = result["results"][0]

import math

images = []
for image in data.get("images") or []:
    width = image.get("imageWidth")
    if type(width) in (int, float) and math.isfinite(width) and width >= 1000:
        images.append({
            "image": image.get("imageUrl"), "sourcePage": image.get("link"),
            "width": width, "height": image.get("imageHeight"),
        })
print(json.dumps(images, ensure_ascii=False, indent=2))

Selected fields from a representative fixture, not a live response or a guarantee that every field/result will be present. This is the content inside the CLI's result property:

{
  "source": "google_images",
  "status": "done",
  "results": [
    {
      "images": [
        {
          "title": "solar panel diagram",
          "link": "https://example.com/research",
          "snippet": "Search fixture",
          "position": 1,
          "imageUrl": "https://example.com/image.png",
          "imageWidth": 1200,
          "imageHeight": 800,
          "source": "Example"
        }
      ]
    }
  ],
  "created_at": "2026-10-12T00:00:00Z",
  "http_status": 200,
  "request_id": "fixture-request"
}

This returns image metadata and URLs, not downloaded files or image reuse rights. Some fields can be absent.

Parameters

| Parameter | Type | Required | Default and constraints | | --- | --- | --- | --- | | query | string | Yes | | | gl | string | No | Pattern: ^[A-Za-z]{2}$. Country code. Set explicitly when needed; omitted values use the search provider’s behavior. | | hl | string | No | Pattern: ^[A-Za-z0-9-]+$. Interface language. Set explicitly when needed; omitted values use the search provider’s behavior. | | location | string | No | | | num | integer | No | Range: 1–100. Requested result count. Actual count varies by query and search type; no fixed value is added when omitted. | | page | integer | No | Range: 1–100. Requested page. Set explicitly for pagination; each page is a separate query. | | tbs | string | No | | | autocorrect | boolean | No | | | mode | string | No | Default: "realtime". Allowed: realtime, async. |

The package includes schema.json with the complete nested schema and examples/query.json. The tools command also returns the current schemas permitted by your key. Fields supplied by the remote source may be missing; preserve original values and source links.

Jobs, errors and billing

For a longer-running query, set mode to "async". Save the returned result.id, create job.json with that job ID, and read it without submitting again:

{"job_id":"job_REPLACE_WITH_RETURNED_ID"}

npx --yes @flashdata-dev/[email protected] call get_job --input job.json > result.json

pending or processing means wait and read the same job later; completed provides the original JSON under result.output. The package never polls or retries paid submissions automatically. A timeout or lost response may still represent charged work: check Jobs before another submission. Each requested search page is a separate paid query; result count is not request count.

CLI exit codes are 0 for a successful operation, 1 for an API/tool failure and 2 for invalid local input/configuration. Input is limited to 256 KiB and each API response to 4 MiB. CLI outputs complete JSON. Async JSON results have a 24-hour availability window.

Connect an MCP client

This same package starts a persistent stdio server with the mcp subcommand:

{
  "mcpServers": {
    "google-images": {
      "command": "npx",
      "args": [
        "--yes",
        "@flashdata-dev/[email protected]",
        "mcp"
      ],
      "env": {
        "FLASHDATA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Use npx.cmd on Windows if your client requires it. Enter your own key through protected client settings. The four tools are google_images, get_pricing, get_job and get_result; the source is fixed, and job reads reject jobs belonging to other sources. API key permissions are rechecked on each operation.

MCP responses longer than 16,000 UTF-16 code units use result_id, chunk and next_offset. Read the remaining chunks with get_result in the same running server, concatenate them in order, then parse JSON. The process retains at most four results for ten minutes. The one-shot CLI has no get_result command because it returns the whole response.

Optional environment settings are FLASHDATA_REQUEST_TIMEOUT_MS (1000–120000, default 65000), FLASHDATA_DATA_API_URL and FLASHDATA_MANAGEMENT_API_URL. Custom URLs must be trusted HTTPS origins; loopback HTTP is accepted for local tests. The package does not load .env files automatically.

Support: [email protected] · Source and issue tracker · FlashData terms · Privacy. This is an independent FlashData integration, not an official Google or YouTube package.