# webfetch MCP server

> Enables AI agents to search for images across 25 providers with structured license metadata and automated attribution.

- Repository: https://github.com/ashlrai/webfetch
- Page: https://hostedmcp.org/servers/ashlrai/webfetch
- Transport: stdio
- Stars: 3
- License: MIT
- Latest version: 0.1.5

## Install

### Claude Code

```sh
claude mcp add --env 'BRAVE_API_KEY=<YOUR_BRAVE_API_KEY>' --env 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' --env 'PIXABAY_API_KEY=<YOUR_PIXABAY_API_KEY>' --env 'SERPAPI_KEY=<YOUR_SERPAPI_KEY>' --env 'UNSPLASH_ACCESS_KEY=<YOUR_UNSPLASH_ACCESS_KEY>' webfetch -- npx -y getwebfetch-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "webfetch": {
      "command": "npx",
      "args": [
        "-y",
        "getwebfetch-mcp"
      ],
      "env": {
        "BRAVE_API_KEY": "<YOUR_BRAVE_API_KEY>",
        "PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>",
        "PIXABAY_API_KEY": "<YOUR_PIXABAY_API_KEY>",
        "SERPAPI_KEY": "<YOUR_SERPAPI_KEY>",
        "UNSPLASH_ACCESS_KEY": "<YOUR_UNSPLASH_ACCESS_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "webfetch": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "getwebfetch-mcp"
      ],
      "env": {
        "BRAVE_API_KEY": "<YOUR_BRAVE_API_KEY>",
        "PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>",
        "PIXABAY_API_KEY": "<YOUR_PIXABAY_API_KEY>",
        "SERPAPI_KEY": "<YOUR_SERPAPI_KEY>",
        "UNSPLASH_ACCESS_KEY": "<YOUR_UNSPLASH_ACCESS_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"webfetch","type":"stdio","command":"npx","args":["-y","getwebfetch-mcp"],"env":{"BRAVE_API_KEY":"<YOUR_BRAVE_API_KEY>","PEXELS_API_KEY":"<YOUR_PEXELS_API_KEY>","PIXABAY_API_KEY":"<YOUR_PIXABAY_API_KEY>","SERPAPI_KEY":"<YOUR_SERPAPI_KEY>","UNSPLASH_ACCESS_KEY":"<YOUR_UNSPLASH_ACCESS_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "webfetch": {
      "command": "npx",
      "args": [
        "-y",
        "getwebfetch-mcp"
      ],
      "env": {
        "BRAVE_API_KEY": "<YOUR_BRAVE_API_KEY>",
        "PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>",
        "PIXABAY_API_KEY": "<YOUR_PIXABAY_API_KEY>",
        "SERPAPI_KEY": "<YOUR_SERPAPI_KEY>",
        "UNSPLASH_ACCESS_KEY": "<YOUR_UNSPLASH_ACCESS_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add webfetch --env 'BRAVE_API_KEY=<YOUR_BRAVE_API_KEY>' --env 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' --env 'PIXABAY_API_KEY=<YOUR_PIXABAY_API_KEY>' --env 'SERPAPI_KEY=<YOUR_SERPAPI_KEY>' --env 'UNSPLASH_ACCESS_KEY=<YOUR_UNSPLASH_ACCESS_KEY>' -- npx -y getwebfetch-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.webfetch]
command = "npx"
args = ["-y", "getwebfetch-mcp"]

[mcp_servers.webfetch.env]
BRAVE_API_KEY = "<YOUR_BRAVE_API_KEY>"
PEXELS_API_KEY = "<YOUR_PEXELS_API_KEY>"
PIXABAY_API_KEY = "<YOUR_PIXABAY_API_KEY>"
SERPAPI_KEY = "<YOUR_SERPAPI_KEY>"
UNSPLASH_ACCESS_KEY = "<YOUR_UNSPLASH_ACCESS_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'BRAVE_API_KEY=<YOUR_BRAVE_API_KEY>' -e 'PEXELS_API_KEY=<YOUR_PEXELS_API_KEY>' -e 'PIXABAY_API_KEY=<YOUR_PIXABAY_API_KEY>' -e 'SERPAPI_KEY=<YOUR_SERPAPI_KEY>' -e 'UNSPLASH_ACCESS_KEY=<YOUR_UNSPLASH_ACCESS_KEY>' webfetch npx -- -y getwebfetch-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "webfetch": {
      "command": "npx",
      "args": [
        "-y",
        "getwebfetch-mcp"
      ],
      "env": {
        "BRAVE_API_KEY": "<YOUR_BRAVE_API_KEY>",
        "PEXELS_API_KEY": "<YOUR_PEXELS_API_KEY>",
        "PIXABAY_API_KEY": "<YOUR_PIXABAY_API_KEY>",
        "SERPAPI_KEY": "<YOUR_SERPAPI_KEY>",
        "UNSPLASH_ACCESS_KEY": "<YOUR_UNSPLASH_ACCESS_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BRAVE_API_KEY` | no | yes | Optional Brave Search API key for Brave image search results. |
| `PEXELS_API_KEY` | no | yes | Optional Pexels API key for Pexels provider results. |
| `PIXABAY_API_KEY` | no | yes | Optional Pixabay API key for Pixabay provider results. |
| `SERPAPI_KEY` | no | yes | Optional SerpApi key for Google Images results. |
| `UNSPLASH_ACCESS_KEY` | no | yes | Optional Unsplash API key for Unsplash provider results. |

## Tools (7)

- `search_images`: Federated image search across license-aware providers (Wikimedia Commons, Openverse, Unsplash, Pexels, Pixabay, iTunes, MusicBrainz CAA, Spotify, Brave). Returns concise ranked candidates with license + attribution. Does NOT auto-download — call `download_image` after. Default safe-only policy includes open, platform-license, editorial/press tags and rejects UNKNOWN. Use open-only for CC/public-domain only. For large batches, prefer CLI: webfetch batch --jsonl --continue-on-error.
- `search_artist_images`: Specialized image search for a musical artist. `kind` selects provider set + query expansion: 'portrait' (Wikimedia + Unsplash + Spotify), 'album' (MusicBrainz CAA + iTunes + Spotify), 'logo' (Wikimedia), 'performing' (Wikimedia + Pexels). Prefer this over `search_images` when building artist/band content.
- `search_album_cover`: Find canonical album artwork. Uses MusicBrainz Cover Art Archive + iTunes + Spotify. Results are EDITORIAL_LICENSED — safe for album identification UI per platform ToS; always show attribution.
- `download_image`: Download an image URL (typically from a prior search_images result) to the local disk cache. Streams with a 20MB hard cap, content-type guard, SHA-256 hash, and returns the cached file path. Host blocklist enforced.
- `fetch_with_license`: Given an arbitrary URL (image or webpage), determine its license via host heuristics + page metadata (<link rel=license>, dc.rights, og tags). Set probe: true to also download the bytes. Use when an agent already has a URL and needs a go/no-go decision before shipping.
- `find_similar`: Reverse-image-search: given a public image URL, find visually similar images. Requires SERPAPI_KEY env var and providers: ['serpapi']. Returns candidates with heuristic licenses — treat results as leads, not shippable.
- `probe_page`: Given a webpage URL, return every <img> on the page with inferred dimensions and a heuristic license per image. Respects robots.txt by default. Use to triage a candidate source page before picking.

## FAQ

### Do I need an API key to use webfetch?

No, many providers like Wikimedia Commons and Openverse do not require an API key for their free tiers.

### Can webfetch help with image licensing?

Yes, it provides structured license tags such as CC0, CC_BY, and platform-specific licenses to help classify images for reuse.

### How does webfetch handle reverse image searches?

It uses the find_similar tool which requires a SerpApi key to return potential leads.

### Can I use webfetch for batch image processing?

Yes, for large volumes of queries, you can use the CLI with the batch command.
