# UnblockingAPI MCP server

> Fetch bot-protected and JavaScript-heavy web pages or parse them into structured JSON using published templates.

- Repository: https://github.com/unblockingapi/mcp
- Page: https://hostedmcp.org/servers/unblockingapi/mcp
- Transport: stdio, remote
- Stars: 2
- License: MIT
- Latest version: 0.8.4

## Install

### Claude Code

```sh
claude mcp add --env 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' mcp -- npx -y @unblockingapi/mcp
```

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

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@unblockingapi/mcp"
      ],
      "env": {
        "UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@unblockingapi/mcp"
      ],
      "env": {
        "UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@unblockingapi/mcp"],"env":{"UNBLOCKINGAPI_KEY":"<YOUR_UNBLOCKINGAPI_KEY>"}}'
```

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

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@unblockingapi/mcp"
      ],
      "env": {
        "UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp --env 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' -- npx -y @unblockingapi/mcp
```

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

```toml
[mcp_servers.mcp]
command = "npx"
args = ["-y", "@unblockingapi/mcp"]

[mcp_servers.mcp.env]
UNBLOCKINGAPI_KEY = "<YOUR_UNBLOCKINGAPI_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' mcp npx -- -y @unblockingapi/mcp
```

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

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@unblockingapi/mcp"
      ],
      "env": {
        "UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `UNBLOCKINGAPI_KEY` | yes | yes | Your UnblockingAPI key from https://unblockingapi.com (500 free credits, no card). |
| `UNBLOCKINGAPI_TIMEOUT_MS` | no | no | Per-request timeout in milliseconds. Default 180000. |

## Tools (7)

- `unblock_fetch`
- `find_templates`
- `get_build_guide`
- `google_search`
- `list_templates`
- `idealista_property`
- `ahrefs_website_authority`

## FAQ

### How can I get structured JSON from a website?

You can use the `unblock_fetch` tool with a `template` parameter to turn a page into named fields instead of markup.

### How do I find a template for a specific website?

Use the `find_templates` tool, which allows you to search by URL, keyword, or category to find a matching parser.

### What happens if a template fails to parse a site?

If a parser fails because the site has changed, the server returns the raw HTML with a `parse_error: true` flag instead of an error.

### Do I need to install anything to use the hosted version?

No, you can add it as a connector and sign in via OAuth without any installation.