📌Overview

Purpose: To provide a server framework that enables interaction with Apify Actors for AI applications and agents via the Model Context Protocol (MCP).

Overview: The Apify Model Context Protocol (MCP) Server offers a versatile environment for AI assistants to utilize various Apify Actors for tasks like web scraping and data extraction. It provides two operational modes: a hosted HTTP server and a local standard input/output (stdio) server. The MCP's structured interface allows for effective communication and task execution through integrated AI clients.

Key Features:

MCP Server Actor: An HTTP server enabling interaction through Server-Sent Events (SSE), facilitating real-time communication with AI assistants.
Dynamic Actor Integration: Supports various Apify Actors, allowing users to perform specialized tasks without needing to manage inputs or call details directly. Users can request data from configurable Actors such as scrapers for social media, search engines, and business directories.

Apify Model Context Protocol (MCP) Server

Implementation of an MCP server for all Apify Actors. This server enables interaction with one or more Apify Actors defined in the MCP Server configuration.

Server Usage Modes

MCP Server Actor – HTTP server accessible via Server-Sent Events (SSE).
MCP Server Stdio – Local server accessible via standard input/output (stdio).

You can also interact with the MCP server using a chat-like UI with the Tester MCP Client.

What does Apify MCP Server do?

The MCP Server Actor allows an AI assistant to use any Apify Actor as a tool to perform specific tasks, such as:

Extracting data from Facebook posts using Facebook Posts Scraper.
Extracting Google Maps contact details using Google Maps Email Extractor.
Scraping Google Search Engine Results Pages using Google Search Results Scraper.
Scraping Instagram posts, profiles, places, photos, and comments using Instagram Scraper.
Searching the web and scraping content via RAG Web Browser.

MCP Clients

You can interact with the Apify MCP server using clients such as:

Claude Desktop (stdio support only)
Visual Studio Code (Stdio and SSE support)
LibreChat (Stdio and SSE support, without Authorization header)
Apify Tester MCP Client (SSE support with Authorization headers)
Other clients available through MCP-related websites.

Example queries you can ask:

Search the web and summarize recent trends about AI Agents.
Find the top 10 best Italian restaurants in San Francisco.
Analyze the Instagram profile of The Rock.
Provide a step-by-step guide on using the Model Context Protocol.
What Apify Actors can I use?

What is the Model Context Protocol?

The Model Context Protocol (MCP) allows AI applications and agents to connect to external tools and data sources securely and in a controlled manner.

More info: Model Context Protocol website

Relation of MCP Server to AI Agents

Apify MCP Server exposes Apify's Actors through MCP protocol, enabling AI Agents and frameworks to use these Actors as tools for data extraction, web searching, and more.

Learn more about AI Agents and building your own on Apify through blog posts and curated collections available online.

Components

Tools

Actors

Any Apify Actor can be used as a tool. By default, the server is pre-configured with:

apify/instagram-scraper
apify/rag-web-browser
lukaskrivka/google-maps-with-contact-details

The MCP server loads the Actor input schema and creates MCP tools corresponding to the Actors. The tool name must be the full Actor name.

Example input to an MCP tool:

{
  "query": "restaurants in San Francisco",
  "maxResults": 3
}

Helper Tools

get-actor-details: Retrieves documentation and schema info about a specific Actor.
discover-actors: Searches Actors by keywords and returns their details.
add-actor-as-tool: Adds an Actor to the available tools list.
remove-actor-from-tool: Removes an Actor from the tools list.

Dynamic tools list updates require an MCP client capable of handling such notifications.

Prompt & Resources

Currently, the server does not provide resources or prompts. Apify's dataset and key-value store will be added as resources in the future.

Usage

The Apify MCP Server can be used as an Apify Actor or run locally on your machine.

MCP Server Actor

Standby web server

Start the server with default actors by sending an HTTP GET request:

https://actors-mcp-server.apify.actor?token=<APIFY_TOKEN>

Or create and run a task specifying desired Actors:

https://USERNAME--actors-mcp-server-task.apify.actor?token=<APIFY_TOKEN>

Interact via Server-Sent Events (SSE)

Use the Tester MCP Client or other SSE-compliant clients to interact with the Server.

Example curl commands:

Initiate SSE connection:

curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>

Send a message using sessionId:

curl -X POST "https://actors-mcp-server.apify.actor/message?token=<APIFY_TOKEN>&session_id=<SESSION_ID>" -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "arguments": { "searchStringsArray": ["restaurants in San Francisco"], "maxCrawledPlacesPerSearch": 3 },
    "name": "lukaskrivka/google-maps-with-contact-details"
  }
}'

Receive streamed JSON response via SSE.

MCP Server at a Local Host

Run the Apify MCP Server locally and use with MCP clients like Claude Desktop or others.

Prerequisites

macOS or Windows
Latest Claude Desktop or other MCP client
Node.js v18+
Apify API Token set as APIFY_TOKEN

Claude Desktop Setup

Download and install Claude Desktop (Windows/macOS).
Enable Developer Mode.
Edit config file:

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

Example configuration:

{
  "mcpServers": {
    "actors-mcp-server": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server"],
      "env": {
        "APIFY_TOKEN": "your-apify-token"
      }
    }
  }
}

You can specify actors:

{
  "mcpServers": {
    "actors-mcp-server": {
      "command": "npx",
      "args": [
        "-y", "@apify/actors-mcp-server",
        "--actors", "lukaskrivka/google-maps-with-contact-details,apify/instagram-scraper"
      ],
      "env": {
        "APIFY_TOKEN": "your-apify-token"
      }
    }
  }
}

Restart Claude Desktop.
Confirm connection via the plugin icon.
Ask queries to test.

Visual Studio Code Setup

You can add the following JSON to User Settings (JSON):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apify_token",
        "description": "Apify API Token",
        "password": true
      }
    ],
    "servers": {
      "actors-mcp-server": {
        "command": "npx",
        "args": ["-y", "@apify/actors-mcp-server"],
        "env": {
          "APIFY_TOKEN": "${input:apify_token}"
        }
      }
    }
  }
}

To specify which Actors to load:

{
  "servers": {
    "actors-mcp-server": {
      "command": "npx",
      "args": [
        "-y", "@apify/actors-mcp-server",
        "--actors", "lukaskrivka/google-maps-with-contact-details,apify/instagram-scraper"
      ],
      "env": {
        "APIFY_TOKEN": "${input:apify_token}"
      }
    }
  }
}

Debugging the MCP Server

Use the MCP Inspector tool:

export APIFY_TOKEN=your-apify-token
npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server

Installing via Smithery

npx -y @smithery/cli install @apify/actors-mcp-server --client claude

Stdio Clients

Create a .env file:

APIFY_TOKEN=your-apify-token

Use example client via stdio:

node dist/examples/clientStdio.js

Development

Prerequisites

Node.js v18+
Python 3.9+
.env file with APIFY_TOKEN

Build package:

npm run build

Running local client with SSE

Run example client script:

node dist/examples/clientSse.js

Debugging tips

Use MCP Inspector as described above for debugging.

Limitations and Feedback

Actor input descriptions truncated to 500 characters.
Enum fields truncated to total of 200 characters.
Required fields marked explicitly.
Special handling for nested properties.
Array item types inferred if missing.
Enum values and examples included in descriptions.

Memory limits:

Each Actor limited to 4GB.
Free users have 8GB limit, with 128MB reserved for the MCP server.

Provide feedback or request features by submitting an issue in Apify Console.

Roadmap (March 2025)

Add Apify dataset and key-value store as resources.
Add tools for Actor logs and Actor runs debugging.

Troubleshooting

Verify Node.js installation (node -v).
Ensure APIFY_TOKEN environment variable is set.
Use the latest MCP server version (@apify/actors-mcp-server@latest).

actors-mcp-server

📌Overview

Apify Model Context Protocol (MCP) Server

Server Usage Modes

What does Apify MCP Server do?

MCP Clients

What is the Model Context Protocol?

Relation of MCP Server to AI Agents

Components

Tools

Actors

Helper Tools

Prompt & Resources

Usage

MCP Server Actor

Standby web server

Interact via Server-Sent Events (SSE)

MCP Server at a Local Host

Prerequisites

Claude Desktop Setup

Visual Studio Code Setup

Debugging the MCP Server

Installing via Smithery

Stdio Clients

Development

Prerequisites

Running local client with SSE

Debugging tips

Limitations and Feedback

Roadmap (March 2025)

Troubleshooting

Learn More