> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapegraphai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Get started with ScrapeGraphAI MCP Server - Connect LLMs to web scraping tools

## Overview

The ScrapeGraphAI MCP Server is a hosted Model Context Protocol (MCP) server that connects Large Language Models (LLMs) to the ScrapeGraphAI API. It lets AI assistants like Cursor, Claude, and Codex scrape, extract, search, crawl, and schedule page monitors through natural language, without writing any code.

## What is MCP?

The Model Context Protocol (MCP) is a standardized way for AI assistants to access external tools and data sources. By connecting the ScrapeGraphAI MCP Server, your AI assistant gains access to the full v2 API surface as callable tools.

## Key Features

<CardGroup cols={2}>
  <Card title="20 Tools" icon="tools">
    Scrape, extract, search, crawl, schedule page monitors, and inspect credits and request history
  </Card>

  <Card title="Hosted, No Install" icon="cloud">
    One HTTPS endpoint — nothing to install, run, or keep up to date
  </Card>

  <Card title="Google or API Key" icon="key">
    Sign in with Google over OAuth 2.1, or authenticate with a ScrapeGraphAI API key
  </Card>

  <Card title="Universal Compatibility" icon="plug">
    Works with Cursor, Claude Desktop, Claude Code, Codex, and any MCP-compatible client
  </Card>
</CardGroup>

## Endpoint

```
https://mcp.scrapegraphai.com/mcp
```

<Note>
  The server speaks **Streamable HTTP**. The legacy HTTP+SSE transport is not supported — if your client offers a transport choice, pick HTTP (not SSE). Individual tool calls run up to 60 seconds; use the async `crawl_*` and `monitor_*` tools for longer jobs.
</Note>

## Quick Start

<Steps>
  <Step title="Choose how to sign in">
    Sign in with Google in the browser, or use an API key from the [ScrapeGraph Dashboard](https://scrapegraphai.com/dashboard).
  </Step>

  <Step title="Choose your client">
    Pick your assistant: <a href="/services/mcp-server/cursor">Cursor</a>, <a href="/services/mcp-server/claude">Claude Desktop</a>, <a href="/services/mcp-server/claude-code">Claude Code</a>, or <a href="/services/mcp-server/codex">Codex</a>.
  </Step>

  <Step title="Add the server">
    Follow the setup guide for your client to register the `sgai` server and authenticate.
  </Step>

  <Step title="Verify">
    Ask your assistant to run the `credits` tool. A balance response confirms the connection works end to end.
  </Step>
</Steps>

## Setup Guides

<CardGroup cols={2}>
  <Card title="Cursor Setup" icon="https://mintcdn.com/scrapegraphaiinc-9e950277/3eC85GCQlhpZd6A9/logo/APP_ICON_2D_DARK.png?fit=max&auto=format&n=3eC85GCQlhpZd6A9&q=85&s=60fd0bda96a73202515632f745e72893" href="/services/mcp-server/cursor" width="1024" height="1024" data-path="logo/APP_ICON_2D_DARK.png">
    Configure ScrapeGraph MCP in Cursor
  </Card>

  <Card title="Claude Desktop Setup" icon="https://mintcdn.com/scrapegraphaiinc-9e950277/PRteAQT1vZQ6-ik0/logo/claude-color.svg?fit=max&auto=format&n=PRteAQT1vZQ6-ik0&q=85&s=4a3fc52a53394c0f568a6171c3ad3a32" href="/services/mcp-server/claude" width="16" height="16" data-path="logo/claude-color.svg">
    Configure ScrapeGraph MCP in Claude Desktop
  </Card>

  <Card title="Claude Code Setup" icon="https://mintcdn.com/scrapegraphaiinc-9e950277/PRteAQT1vZQ6-ik0/logo/claude-color.svg?fit=max&auto=format&n=PRteAQT1vZQ6-ik0&q=85&s=4a3fc52a53394c0f568a6171c3ad3a32" href="/services/mcp-server/claude-code" width="16" height="16" data-path="logo/claude-color.svg">
    Configure ScrapeGraph MCP in Claude Code
  </Card>

  <Card title="Codex Setup" icon="https://mintcdn.com/scrapegraphaiinc-9e950277/xlfXN_oXuKKdNRrP/logo/codex.svg?fit=max&auto=format&n=xlfXN_oXuKKdNRrP&q=85&s=852a9f2b10efddae68f3dfe9599843c7" href="/services/mcp-server/codex" width="20" height="20" data-path="logo/codex.svg">
    Configure ScrapeGraph MCP in Codex
  </Card>
</CardGroup>

## Authentication

### Sign in with Google (recommended)

Add the server without any credentials. On first connection the client discovers the OAuth metadata, registers itself, and opens the ScrapeGraphAI login page in your browser.

```json theme={null}
{
  "mcpServers": {
    "sgai": {
      "url": "https://mcp.scrapegraphai.com/mcp"
    }
  }
}
```

<Steps>
  <Step title="Restart your MCP client">
    Restart the client after saving its MCP configuration so that it loads the new `sgai` server.
  </Step>

  <Step title="Start authentication">
    Run <code>/mcp</code> in your client, select <code>sgai</code>, and choose the option to authenticate. In Claude Code and Codex you can also start the flow from the terminal with <code>claude mcp login sgai</code> or <code>codex mcp login sgai</code>.
  </Step>

  <Step title="Continue with Google">
    In the browser window that opens, select <strong>Continue with Google</strong> and use the Google account associated with your ScrapeGraphAI account.
  </Step>

  <Step title="Confirm the connection">
    Return to your client after you see <strong>Authentication successful. Connected to sgai.</strong> The server is ready to use.
  </Step>
</Steps>

The flow is standard OAuth 2.1 with PKCE (`S256`) and dynamic client registration, requesting the `mcp:use` scope. Tools run against the workspace tied to the account you signed in with.

### Authenticate with an API key

Set your API key in the `SGAI_API_KEY` environment variable and reference it from the client config:

```json theme={null}
{
  "mcpServers": {
    "sgai": {
      "url": "https://mcp.scrapegraphai.com/mcp",
      "bearer_token_env_var": "SGAI_API_KEY"
    }
  }
}
```

<Note>
  Clients that send raw headers instead can pass the key as `Authorization: Bearer sgai-...`, `SGAI-APIKEY`, or `X-API-Key`. Any request carrying an API key skips the OAuth flow entirely.
</Note>

### Verify the connection

Ask your assistant to run the `credits` tool. A successful balance response confirms that both authentication and tool execution are working.

## Available Tools

Every tool maps to a [v2 API](/api-reference/introduction) endpoint and runs against the workspace you authenticated with.

### Scraping

| Tool        | Description                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| **scrape**  | Fetch a URL as markdown (default), html, screenshot, branding, links, images, summary, or json — `POST /api/scrape` |
| **extract** | AI-powered structured extraction from a URL, raw HTML, or markdown — `POST /api/extract`                            |
| **search**  | Search the web and extract structured data from the results (1–20 results, default 3) — `POST /api/search`          |

### Crawling

| Tool              | Description                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| **crawl\_start**  | Start an async multi-page crawl (default 50 pages, depth 2; max 1000 pages) — `POST /api/crawl` |
| **crawl\_get**    | Get crawl status and pages — `GET /api/crawl/:id`                                               |
| **crawl\_pages**  | Get paginated crawl pages (default 50 per page, max 100) — `GET /api/crawl/:id/pages`           |
| **crawl\_stop**   | Stop a running crawl — `POST /api/crawl/:id/stop`                                               |
| **crawl\_resume** | Resume a paused crawl — `POST /api/crawl/:id/resume`                                            |
| **crawl\_delete** | Delete a crawl — `DELETE /api/crawl/:id`                                                        |

### Monitors

| Tool                  | Description                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **monitor\_create**   | Schedule a page-change monitor with a cron expression or shorthand (e.g. `1h`) — `POST /api/monitor` |
| **monitor\_list**     | List all monitors — `GET /api/monitor`                                                               |
| **monitor\_get**      | Get monitor details — `GET /api/monitor/:id`                                                         |
| **monitor\_update**   | Update a monitor's name, interval, formats, or webhook — `PATCH /api/monitor/:id`                    |
| **monitor\_pause**    | Pause a running monitor — `POST /api/monitor/:id/pause`                                              |
| **monitor\_resume**   | Resume a paused monitor — `POST /api/monitor/:id/resume`                                             |
| **monitor\_delete**   | Delete a monitor — `DELETE /api/monitor/:id`                                                         |
| **monitor\_activity** | Poll a monitor's tick history (default 20 per page, max 100) — `GET /api/monitor/:id/activity`       |

### Account

| Tool              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| **credits**       | Check your credit balance — `GET /api/credits`                     |
| **history\_list** | Browse request history, filterable by service — `GET /api/history` |
| **history\_get**  | Get a single request history entry — `GET /api/history/:id`        |

<Note>
  **Coming from the legacy `scrapegraph-mcp` package?** The hosted server exposes the v2 API under its canonical names:

  | Legacy tool                   | Now                                                                                        |
  | ----------------------------- | ------------------------------------------------------------------------------------------ |
  | `smartscraper`                | `extract`                                                                                  |
  | `searchscraper`               | `search`                                                                                   |
  | `markdownify`                 | `scrape` with `formats: ["markdown"]`                                                      |
  | `smartcrawler_initiate`       | `crawl_start`                                                                              |
  | `smartcrawler_fetch_results`  | `crawl_get`, or `crawl_pages` for pagination                                               |
  | `sgai_history`                | `history_list`                                                                             |
  | `generate_schema`             | Removed — pass a JSON Schema directly via the `schema` parameter on `extract` and `search` |
  | `sitemap`, `agentic_scrapper` | No direct equivalent on the hosted server                                                  |
</Note>

## Use Cases

* **Research & Analysis** — Extract data from multiple sources for research
* **Content Aggregation** — Collect and structure content from websites
* **Market Intelligence** — Monitor competitors and track page changes over time
* **Lead Generation** — Extract contact information and company data
* **Data Collection** — Build datasets from web sources

## Next Steps

* Set up your client: <a href="/services/mcp-server/cursor">Cursor</a>, <a href="/services/mcp-server/claude">Claude Desktop</a>, <a href="/services/mcp-server/claude-code">Claude Code</a>, or <a href="/services/mcp-server/codex">Codex</a>
* Browse the [v2 API reference](/api-reference/introduction) for full parameter documentation on every tool

<Card title="Ready to Start?" icon="rocket" href="/services/mcp-server/cursor">
  Choose your client and start scraping with AI!
</Card>