Skip to content

feat: Add video tutorial into the Actor README. Simplify README #175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 17, 2025
Merged

feat: Add video tutorial into the Actor README. Simplify README #175

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 35 additions & 118 deletions .actor/ACTOR.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Apify Model Context Protocol (MCP) Server

> **⚠️ Legacy solution notice**
> This Actor is legacy implementation of the Apify MCP Server. For the current and actively maintained solution, please visit **[mcp.apify.com](https://mcp.apify.com)** where you'll find the latest server, comprehensive documentation, and setup guides.
> **💾 Legacy**
> This Actor is a legacy implementation of the Apify MCP Server. For the current and actively maintained solution, please visit **[mcp.apify.com](https://mcp.apify.com)** where you'll find the latest server, comprehensive documentation, and setup guides.

[![Actors MCP Server](https://apify.com/actor-badge?actor=apify/actors-mcp-server)](https://apify.com/apify/actors-mcp-server)

Implementation of an MCP server for all [Apify Actors](https://apify.com/store).
This server enables interaction with one or more Apify Actors that can be defined in the MCP Server configuration.

The server can be used in two ways:
- **🇦 [MCP Server Actor](https://apify.com/apify/actors-mcp-server)** – HTTP server accessible via Server-Sent Events (SSE), see [guide](#-mcp-server-actor)
- **🇦 [MCP Server Actor](https://apify.com/apify/actors-mcp-server)** – HTTP server accessible via http-streamable transport, see [guide](#-remote-mcp-server)
- **⾕ MCP Server Stdio** – Local server available via standard input/output (stdio), see [guide](#-mcp-server-at-a-local-host)

You can also interact with the MCP server using a chat-like UI with 💬 [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
Expand All @@ -24,13 +24,17 @@ For example, it can:
- Use [Instagram Scraper](https://apify.com/apify/instagram-scraper) to scrape Instagram posts, profiles, places, photos, and comments
- Use [RAG Web Browser](https://apify.com/apify/web-scraper) to search the web, scrape the top N URLs, and return their content

Learn about the key features and capabilities in the **Apify MCP Server Tutorial: Integrate 5,000+ Apify Actors and Agents Into Claude** video

[Apify MCP Server Tutorial: Integrate 5,000+ Apify Actors and Agents Into Claude](https://www.youtube.com/watch?v=BKu8H91uCTg)

# MCP Clients

To interact with the Apify MCP server, you can use MCP clients such as:
- [Claude Desktop](https://claude.ai/download) (only Stdio support)
- [Visual Studio Code](https://code.visualstudio.com/) (Stdio and SSE support)
- [LibreChat](https://www.librechat.ai/) (Stdio and SSE support, yet without Authorization header)
- [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) (SSE support with Authorization headers)
- [Claude Desktop](https://claude.ai/download)
- [Visual Studio Code](https://code.visualstudio.com/)
- [LibreChat](https://www.librechat.ai/)
- [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
- Other clients at [https://modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients)
- More clients at [https://glama.ai/mcp/clients](https://glama.ai/mcp/clients)

Expand All @@ -45,8 +49,7 @@ The following image shows how the Apify MCP server interacts with the Apify plat

![Actors-MCP-server](https://raw.githubusercontent.com/apify/actors-mcp-server/refs/heads/master/docs/actors-mcp-server.png)

With the MCP Tester client you can load Actors dynamically but this is not yet supported by other MCP clients.
We also plan to add more features, see [Roadmap](#-roadmap-march-2025) for more details.
With the MCP Tester client you can load Actors dynamically but this might not be supported by other MCP clients.

# 🔄 What is the Model Context Protocol?

Expand All @@ -68,32 +71,24 @@ Interested in building and monetizing your own AI agent on Apify? Check out our

### Actors
Any [Apify Actor](https://apify.com/store) can be used as a tool.
By default, the server is pre-configured with the Actors specified below, but this can be overridden by providing the `?actors` URL query parameter.

```text
'apify/rag-web-browser'
```
For example, to additionally load the `apify/instagram-scraper` Actor, you can start the server with the following URL:
By default, the server is pre-configured with the `apify/rag-web-browser` Actor, but this can be overridden by providing the `actors` URL query parameter.
For example, to load both `apify/rag-web-browser` and `apify/instagram-scraper`, start the server with the following URL:
```text
https://actors-mcp-server.apify.actor?token=<APIFY_TOKEN>&actors=apify/rag-web-browser,apify/instagram-scraper
```

The MCP server loads the Actor input schema and creates MCP tools corresponding to the Actors.
See this example of input schema for the [RAG Web Browser](https://apify.com/apify/rag-web-browser/input-schema).
The MCP server automatically loads the input schema for each Actor to create corresponding MCP tools.
See this example of an input schema for the [RAG Web Browser](https://apify.com/apify/rag-web-browser/input-schema).

The tool name must always be the full Actor name, such as `apify/rag-web-browser`.
The arguments for an MCP tool represent the input parameters of the Actor.
For example, for the `apify/rag-web-browser` Actor, the arguments are:
The tool name is always the full Actor name (e.g., `apify/rag-web-browser`), and its arguments correspond to the Actor's input parameters. For instance:

```json
{
"query": "restaurants in San Francisco",
"maxResults": 3
}
```
You don't need to specify the input parameters or which Actor to call; everything is managed by an LLM.
When a tool is called, the arguments are automatically passed to the Actor by the LLM.
You can refer to the specific Actor's documentation for a list of available arguments.
You don't need to specify which Actor to call or what its input parameters are; the LLM handles this automatically. To understand an Actor's full capabilities, you can find the complete list of arguments in its documentation.

### Helper tools
One of the powerful features of MCP with Apify is dynamic actor tooling – the ability for an AI agent to find new tools (Actors) as needed and incorporate them. Here are some special MCP operations and how Apify MCP Server supports them:
Expand All @@ -114,43 +109,41 @@ We plan to add [Apify's dataset](https://docs.apify.com/platform/storage/dataset
The Apify MCP Server can be used in two ways: **as an Apify Actor** running on the Apify platform
or as a **local server** running on your machine.

## 🇦 MCP Server Actor
## 🇦 Remote MCP Server

### Standby web server
The MCP server is an Apify Actor that runs in [**Standby mode**](https://docs.apify.com/platform/actors/running/standby) with an HTTP web server that receives and processes requests.

The Actor runs in [**Standby mode**](https://docs.apify.com/platform/actors/running/standby) with an HTTP web server that receives and processes requests.

To start the server with default Actors, send an HTTP GET request with your [Apify API token](https://console.apify.com/settings/integrations) to the following URL:
To use the server with default set of Actors, add your [Apify API token](https://console.apify.com/settings/integrations) to the following URL:
```
https://actors-mcp-server.apify.actor?token=<APIFY_TOKEN>
```
It is also possible to start the MCP server with a different set of Actors.

It is also possible to use the MCP server with a different set of Actors.
To do this, create a [task](https://docs.apify.com/platform/actors/running/tasks) and specify the list of Actors you want to use.

Then, run the task in Standby mode with the selected Actors:
```shell
```text
https://USERNAME--actors-mcp-server-task.apify.actor?token=<APIFY_TOKEN>
```

You can find a list of all available Actors in the [Apify Store](https://apify.com/store).

#### 💬 Interact with the MCP Server over SSE
#### 💬 Interact with the MCP Server over HTTP-Streamable transport

Once the server is running, you can interact with Server-Sent Events (SSE) to send messages to the server and receive responses.
Once the server is running, you can interact with it using http-streamable transport.
The easiest way is to use [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) on Apify.

[Claude Desktop](https://claude.ai/download) currently lacks SSE support, but you can use it with Stdio transport; see [MCP Server at a local host](#-mcp-server-at-a-local-host) for more details.
[Claude Desktop](https://claude.ai/download) does not support remote MCP servers. To use it, you must run the server locally. See the [local host guide](#-mcp-server-at-a-local-host) for setup instructions.
Note: The free version of Claude Desktop may experience intermittent connection issues with the server.

In the client settings, you need to provide server configuration:
```json
{
"mcpServers": {
"apify": {
"type": "sse",
"url": "https://actors-mcp-server.apify.actor/sse",
"env": {
"APIFY_TOKEN": "your-apify-token"
"type": "http",
"url": "https://actors-mcp-server.apify.actor",
"headers": {
"Authorization": "Bearer your-apify-token"
}
}
}
Expand All @@ -160,7 +153,6 @@ In the client settings, you need to provide server configuration:
## ⾕ MCP Server at a local host

You can run the Apify MCP Server on your local machine by configuring it with Claude Desktop or any other [MCP client](https://modelcontextprotocol.io/clients).
You can also use [Smithery](https://smithery.ai/server/@apify/actors-mcp-server) to install the server automatically.

### Prerequisites

Expand Down Expand Up @@ -248,8 +240,6 @@ For one-click installation, click one of the install buttons below:

##### Manual installation

You can manually install the Apify MCP Server in VS Code. First, click one of the install buttons at the top of this section for a one-click installation.

Alternatively, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.

```json
Expand Down Expand Up @@ -297,64 +287,7 @@ If you want to specify which Actors to load, you can add the `--actors` argument
}
```

#### VS Code

For one-click installation, click one of the install buttons below:

[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=actors-mcp-server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40apify%2Factors-mcp-server%22%5D%2C%22env%22%3A%7B%22APIFY_TOKEN%22%3A%22%24%7Binput%3Aapify_token%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apify_token%22%2C%22description%22%3A%22Apify+API+Token%22%2C%22password%22%3Atrue%7D%5D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=actors-mcp-server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40apify%2Factors-mcp-server%22%5D%2C%22env%22%3A%7B%22APIFY_TOKEN%22%3A%22%24%7Binput%3Aapify_token%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apify_token%22%2C%22description%22%3A%22Apify+API+Token%22%2C%22password%22%3Atrue%7D%5D&quality=insiders)

##### Manual installation

You can manually install the Apify MCP Server in VS Code. First, click one of the install buttons at the top of this section for a one-click installation.

Alternatively, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.

```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}"
}
}
}
}
}
```

Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace - just omit the top-level `mcp {}` key. This will allow you to share the configuration with others.

If you want to specify which Actors to load, you can add the `--actors` argument:

```json
{
"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 NPM package @apify/actors-mcp-server with @modelcontextprotocol/inspector
#### Debugging the installed NPM package

To debug the server, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:

Expand All @@ -381,17 +314,7 @@ Build the actor-mcp-server package:
npm run build
```

## Local client (SSE)

To test the server with the SSE transport, you can use the script `examples/clientSse.ts`:
Currently, the Node.js client does not support establishing a connection to a remote server with custom headers.
You need to change the URL to your local server URL in the script.

```bash
node dist/examples/clientSse.js
```

## Debugging
## Debugging from source

Since MCP servers operate over standard input/output (stdio), debugging can be challenging.
For the best debugging experience, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
Expand All @@ -407,7 +330,7 @@ Upon launching, the Inspector will display a URL that you can access in your bro

## ⓘ Limitations and feedback

The Actor input schema is processed to be compatible with most MCP clients while adhering to [JSON Schema](https://json-schema.org/) standards. The processing includes:
To ensure compatibility with various MCP clients, the Actor input schema is automatically processed while adhering to [JSON Schema](https://json-schema.org/) standards. Key adjustments include:
- **Descriptions** are truncated to 500 characters (as defined in `MAX_DESCRIPTION_LENGTH`).
- **Enum fields** are truncated to a maximum combined length of 200 characters for all elements (as defined in `ACTOR_ENUM_MAX_LENGTH`).
- **Required fields** are explicitly marked with a "REQUIRED" prefix in their descriptions for compatibility with frameworks that may not handle JSON schema properly.
Expand All @@ -420,11 +343,6 @@ Free users have an 8GB limit, 128MB needs to be allocated for running `Actors-MC

If you need other features or have any feedback, [submit an issue](https://console.apify.com/actors/1lSvMAaRcadrM1Vgv/issues) in Apify Console to let us know.

# 🚀 Roadmap (March 2025)

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

# 🐛 Troubleshooting

- Make sure you have the `node` installed by running `node -v`
Expand All @@ -438,6 +356,5 @@ If you need other features or have any feedback, [submit an issue](https://conso
- [What is MCP and why does it matter?](https://blog.apify.com/what-is-model-context-protocol/)
- [How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/)
- [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
- [AI agent workflow: building an agent to query Apify datasets](https://blog.apify.com/ai-agent-workflow/)
- [MCP Client development guide](https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-client-development-guide.md)
- [How to build and monetize an AI agent on Apify](https://blog.apify.com/how-to-build-an-ai-agent/)
- [Apify MCP Server Tutorial: Integrate 5,000+ Apify Actors and Agents Into Claude](https://www.youtube.com/watch?v=BKu8H91uCTg&ab_channel=Apify)