Scrappey MCP server for AI agents

The Scrappey MCP Server provides a bridge between AI models and Scrappey's web automation platform, allowing you to manage browser sessions, send HTTP requests through Scrappey's infrastructure, and execute browser actions while handling various anti-bot protections automatically.

Installation

To set up the Scrappey MCP Server, you need to:

Get your Scrappey API key from Scrappey.com
Set up your environment variable:

SCRAPPEY_API_KEY=your_api_key_here

Using the MCP Server

The server can be accessed directly at smithery.ai/server/@pim97/mcp-server-scrappey, or you can interact with it programmatically using the tools described below.

Available Tools

Creating a Session

Use scrappey_create_session to create a new browser session that persists cookies and other state:

{
  "name": "scrappey_create_session",
  "proxy": "http://user:pass@ip:port"  // Optional: Custom proxy, leave empty for default
}

Destroying a Session

Use scrappey_destroy_session to properly close a browser session:

{
  "name": "scrappey_destroy_session",
  "session": "session_id_here"  // Required: The session ID to destroy
}

Sending HTTP Requests

Use scrappey_request to send HTTP requests through the Scrappey infrastructure:

{
  "name": "scrappey_request",
  "cmd": "request.get",  // Required: request.get, request.post, etc.
  "url": "https://example.com",  // Required: Target URL
  "session": "session_id_here",  // Required: Session ID to use
  "postData": "key=value",  // Optional: POST data
  "customHeaders": {  // Optional: Custom headers
    "User-Agent": "custom-agent"
  }
}

Executing Browser Actions

Use scrappey_browser_action to execute browser automation actions:

{
  "name": "scrappey_browser_action",
  "session": "session_id_here",  // Required: Session ID to use
  "browserActions": [  // Required: Array of actions to perform
    {
      "type": "click",  // Action type: click, hover, type, scroll, wait
      "cssSelector": ".button",  // CSS selector for element
      "text": "Hello",  // Text to type (for type action)
      "wait": 1000  // Wait time in ms
    }
  ]
}

Typical Workflow

Here's how to use the server in a typical workflow:

First, create a session:

{
  "name": "scrappey_create_session"
}

Use the returned session ID for subsequent requests:

{
  "name": "scrappey_request",
  "cmd": "request.get",
  "url": "https://example.com",
  "session": "returned_session_id"
}

Perform browser actions if needed:

{
  "name": "scrappey_browser_action",
  "session": "returned_session_id",
  "browserActions": [
    {
      "type": "click",
      "cssSelector": "#login-button"
    },
    {
      "type": "type",
      "cssSelector": "#username",
      "text": "myuser"
    }
  ]
}

Clean up by destroying the session when done:

{
  "name": "scrappey_destroy_session",
  "session": "returned_session_id"
}

Best Practices

For optimal performance and reliability:

Always destroy sessions when you're done with them
Reuse sessions when making multiple requests to the same site
Use appropriate wait times between actions for more human-like behavior
Check if a session exists before using it

Error Handling

The server returns error messages with details when something goes wrong. Common errors include:

Invalid session IDs
Network timeouts
Invalid selectors for browser actions
Anti-bot protection failures

When an error occurs, check the response message for details on how to resolve the issue.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "scrappey" '{"command":"npx","args":["-y","mcp-server-scrappey"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "scrappey": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-server-scrappey"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "scrappey": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-server-scrappey"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect