# @domscout/mcp

Use domscout as MCP tools to read pages as Markdown, capture screenshots,
extract structured data, inspect interactive structure, automate browser flows,
and crawl allowlisted sites.

## Install

Create an API key at <https://www.domscout.io/dashboard/api-keys>, then add the
server to your client. Node.js 20 or newer is the only requirement; `npx`
fetches and runs it, so there is nothing to install or build.

**Claude Code**

```bash
claude mcp add --transport stdio --env DOMSCOUT_API_KEY=YOUR_API_KEY domscout -- npx -y @domscout/mcp
```

**Claude Desktop, Cursor, VS Code, and any other MCP client**

```json
{
  "mcpServers": {
    "domscout": {
      "command": "npx",
      "args": ["-y", "@domscout/mcp"],
      "env": {
        "DOMSCOUT_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

One-click install buttons for Cursor and VS Code are on the
[documentation page](https://www.domscout.io/docs/mcp).

### Environment

| Variable | Required | Purpose |
| --- | --- | --- |
| `DOMSCOUT_API_KEY` | For tool calls | Your API key. The server starts and lists its tools without one; every tool call needs it. |
| `DOMSCOUT_BASE_URL` | No | Overrides the current production gateway for an intentionally separate deployment. |
| `DOMSCOUT_DOCS_BASE_URL` | No | Where the contract resources (`/llms-full.txt`, `/openapi.json`) are fetched from. Separate from `DOMSCOUT_BASE_URL` because the docs are served by the marketing site, not the API gateway, and that host has no `/llms-full.txt`. Defaults to `https://www.domscout.io`. |

The default targets `https://api.domscout.io`. API requests do not follow
redirects, so the key is never re-sent to another URL: a `DOMSCOUT_BASE_URL`
that answers with a redirect fails with an error naming the status. Point it at
the final URL instead.
Verify the key in the dashboard before connecting a client; never commit or
paste the key into prompts.

## Tools

| Tool | Cost | What it does |
| --- | --- | --- |
| `domscout_check_credits` | free | Balance, quota, rate limit, and price list |
| `domscout_extract_markdown` | 1 | Read a page as clean Markdown (`fast:true` skips the browser) |
| `domscout_capture_screenshot` | 1–3 | Capture PNG/JPEG/WebP/PDF |
| `domscout_extract_data` | 2 | Extract named fields as typed JSON |
| `domscout_inspect_page` | 2 | Read the accessibility tree and interactive elements |
| `domscout_automate_page` | 1–2 | Run allowed actions and capture the result |
| `domscout_crawl_site` | 1/page | Run a bounded, allowlisted, robots-respecting crawl |
| `domscout_get_job` | free | Poll a durable job, batch, or crawl |
| `domscout_cancel_job` | free | Cancel one durable job |
| `domscout_send_feedback` | free | Send product feedback |

A request never costs more than 10 credits. Tool results include the request
cost and remaining balance.

Completed screenshot, grid, skeleton and timeline jobs return images as MCP
image blocks. PDF results use
the same inline size limit for synchronous captures and completed jobs; larger
PDFs return metadata and retrieval guidance. Job status and identifiers remain
available alongside the capture result.

## Resources

| URI | Contents |
| --- | --- |
| `domscout://docs` | API reference |
| `domscout://openapi` | OpenAPI 3.1 contract |

## Security

The MCP server sends an `x-api-key` to the configured API host and reads the
response. It has no browser, database, or billing credential. Keep the key in
the MCP client environment block; do not commit it or paste it into prompts.


## Links

- [Documentation](https://www.domscout.io/docs/mcp)
- [API reference](https://www.domscout.io/docs)
- [Issues](https://github.com/jkresearch8/domscout-mcp/issues)

## License

MIT. See [LICENSE](LICENSE).