Servidor de protocolo de contexto de modelo (MCP) de Apify

Implementación de un servidor MCP para todos los actores de Apify . Este servidor permite la interacción con uno o más actores de Apify, definidos en la configuración del servidor MCP.

El servidor se puede utilizar de dos maneras:

• 🇦 Actor de servidor MCP : servidor HTTP accesible a través de eventos enviados por el servidor (SSE), consulte la guía
• ⾕ MCP Server Stdio : servidor local disponible a través de entrada/salida estándar (stdio), consulte la guía

También puedes interactuar con el servidor MCP mediante una interfaz de usuario tipo chat con 💬 Tester MCP Client

🎯 ¿Qué hace el servidor MCP de Apify?

El Actor de Servidor MCP permite que un asistente de IA utilice cualquier Actor de Apify como herramienta para realizar una tarea específica. Por ejemplo, puede:

• Utilice Facebook Posts Scraper para extraer datos de publicaciones de Facebook de varias páginas/perfiles
• Utilice Google Maps Email Extractor para extraer detalles de contacto de Google Maps
• Utilice Google Search Results Scraper para rastrear las páginas de resultados del motor de búsqueda de Google (SERP)
• Utilice Instagram Scraper para extraer información de publicaciones, perfiles, lugares, fotos y comentarios de Instagram.
• Utilice el navegador web RAG para buscar en la web, extraer las N URL principales y devolver su contenido

Clientes de MCP

Para interactuar con el servidor MCP de Apify, puede utilizar clientes MCP como:

• Claude Desktop (solo compatible con Stdio)
• Visual Studio Code (compatibilidad con Stdio y SSE)
• LibreChat (compatible con Stdio y SSE, pero sin encabezado de autorización)
• Cliente MCP de Apify Tester (compatibilidad con SSE y encabezados de autorización)
• Otros clientes en https://modelcontextprotocol.io/clients
• Más clientes en https://glama.ai/mcp/clients

Cuando tengas Actores integrados con el servidor MCP, podrás preguntar:

• Busque en la web y resuma las tendencias recientes sobre los agentes de IA.
• Encuentra los 10 mejores restaurantes italianos de San Francisco.
• Encuentra y analiza el perfil de Instagram de The Rock.
• Proporcionar una guía paso a paso sobre el uso del Protocolo de Contexto de Modelo con URL de origen.
• ¿Qué actores de Apify puedo utilizar?

La siguiente imagen muestra cómo el servidor Apify MCP interactúa con la plataforma Apify y los clientes de IA:

Con el cliente MCP Tester, puede cargar actores dinámicamente, pero otros clientes MCP aún no lo admiten. También planeamos añadir más funciones; consulte la hoja de ruta para obtener más detalles.

🔄¿Qué es el Protocolo de Contexto Modelo?

El Protocolo de Contexto de Modelo (MCP) permite que las aplicaciones de IA (y sus agentes), como Claude Desktop, se conecten a herramientas y fuentes de datos externas. MCP es un protocolo abierto que facilita interacciones seguras y controladas entre aplicaciones de IA, agentes de IA y recursos locales o remotos.

Para obtener más información, consulte el sitio web del Protocolo de Contexto de Modelo o la publicación del blog ¿Qué es MCP y por qué es importante?

🤖 ¿Cómo se relaciona MCP Server con los agentes de IA?

El servidor MCP de Apify expone los actores de Apify a través del protocolo MCP, lo que permite que los agentes de IA o los marcos que implementan el protocolo MCP accedan a todos los actores de Apify como herramientas para la extracción de datos, la búsqueda web y otras tareas.

Para obtener más información sobre los agentes de IA, consulta nuestra entrada de blog: ¿Qué son los agentes de IA? y explora la colección de agentes de IA de Apify. ¿Te interesa crear y monetizar tu propio agente de IA en Apify? Consulta nuestra guía paso a paso para crear, publicar y monetizar agentes de IA en la plataforma Apify.

🧱 Componentes

Herramientas

Actores

Cualquier actor de Apify puede usarse como herramienta. De forma predeterminada, el servidor está preconfigurado con los actores especificados a continuación, pero esto puede anularse proporcionando la entrada del actor.

El servidor MCP carga el esquema de entrada del actor y crea las herramientas MCP correspondientes. Vea este ejemplo de esquema de entrada para el navegador web RAG .

El nombre de la herramienta siempre debe ser el nombre completo del actor, como apify/rag-web-browser . Los argumentos de una herramienta MCP representan los parámetros de entrada del actor. Por ejemplo, para el actor apify/rag-web-browser , los argumentos son:

No es necesario especificar los parámetros de entrada ni a qué actor llamar; todo lo gestiona un LLM. Al llamar a una herramienta, el LLM pasa automáticamente los argumentos al actor. Puede consultar la documentación específica del actor para obtener una lista de los argumentos disponibles.

Herramientas de ayuda

El servidor proporciona un conjunto de herramientas útiles para descubrir actores disponibles y recuperar sus detalles:

• get-actor-details : recupera documentación, esquema de entrada y detalles sobre un actor específico.
• discover-actors : busca actores relevantes utilizando palabras clave y devuelve sus detalles.

También existen herramientas para administrar la lista de herramientas disponibles. Sin embargo, agregar y eliminar herramientas dinámicamente requiere que el cliente MCP tenga la capacidad de actualizar la lista de herramientas (manejar ToolListChangedNotificationSchema ), lo cual no suele ser compatible.

Puedes probar esta funcionalidad con el actor cliente MCP de Apify Tester . Para habilitarla, configura el parámetro enableActorAutoLoading .

• add-actor-as-tool : agrega un actor por nombre a la lista de herramientas disponibles sin ejecutarlo, requiriendo el consentimiento del usuario para ejecutarlo más tarde.
• remove-actor-from-tool : elimina un actor por nombre de la lista de herramientas disponibles cuando ya no es necesario.

Aviso y recursos

El servidor no proporciona recursos ni solicitudes. Planeamos agregar el conjunto de datos de Apify y el almacén de claves-valor como recursos en el futuro.

⚙️ Uso

El servidor Apify MCP se puede utilizar de dos maneras: como un actor Apify que se ejecuta en la plataforma Apify o como un servidor local que se ejecuta en su máquina.

Actor de servidor MCP

Servidor web en espera

El actor se ejecuta en modo de espera con un servidor web HTTP que recibe y procesa solicitudes.

Para iniciar el servidor con actores predeterminados, envíe una solicitud HTTP GET con su token de API de Apify a la siguiente URL:

También es posible iniciar el servidor MCP con un conjunto diferente de actores. Para ello, cree una tarea y especifique la lista de actores que desea utilizar.

Luego, ejecute la tarea en modo de espera con los actores seleccionados:

Puede encontrar una lista de todos los actores disponibles en Apify Store .

💬 Interactúe con el servidor MCP a través de SSE

Una vez que el servidor esté en funcionamiento, puede interactuar con los Eventos Enviados por el Servidor (SSE) para enviar mensajes al servidor y recibir respuestas. La forma más sencilla es usar el Cliente Tester MCP en Apify.

Claude Desktop actualmente no es compatible con SSE, pero puede usarlo con el transporte Stdio; consulte Servidor MCP en un host local para más detalles. Nota: La versión gratuita de Claude Desktop puede experimentar problemas de conexión intermitentes con el servidor.

En la configuración del cliente, debe proporcionar la configuración del servidor:

Alternativamente, puede utilizar el script clientSse.ts o probar el servidor utilizando los comandos curl </>.

1. Inicie eventos enviados por el servidor (SSE) enviando una solicitud GET a la siguiente URL:
   curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>
   El servidor responderá con un sessionId , que puedes usar para enviar mensajes al servidor:
   event: endpoint data: /message?sessionId=a1b
2. Envía un mensaje al servidor realizando una solicitud POST con el sessionId :
   curl -X POST "https://actors-mcp-server.apify.actor/message?token=<APIFY_TOKEN>&session_id=a1b" -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" } }'
   El servidor MCP iniciará el actor lukaskrivka/google-maps-with-contact-details con los argumentos proporcionados como parámetros de entrada. Para esta solicitud POST, el servidor responderá con:
   Accepted
3. Recibir la respuesta. El servidor invocará al actor especificado como herramienta utilizando los parámetros de consulta proporcionados y transmitirá la respuesta al cliente mediante SSE. La respuesta se devolverá como texto JSON.
   event: message data: {"result":{"content":[{"type":"text","text":"{\"searchString\":\"restaurants in San Francisco\",\"rank\":1,\"title\":\"Gary Danko\",\"description\":\"Renowned chef Gary Danko's fixed-price menus of American cuisine ... \",\"price\":\"$100+\"...}}]}}

⾕ Servidor MCP en un host local

Puede ejecutar el servidor Apify MCP en su equipo local configurándolo con Claude Desktop o cualquier otro cliente MCP . También puede usar Smithery para instalar el servidor automáticamente.

Prerrequisitos

• MacOS o Windows
• Se debe instalar la última versión de Claude Desktop (u otro cliente MCP)
• Node.js (v18 o superior)
• Token de API de Apify ( APIFY_TOKEN )

Asegúrese de tener el node y npx instalados correctamente:

De lo contrario, siga esta guía para instalar Node.js: Descargar e instalar Node.js y npm .

Escritorio de Claude

Para configurar Claude Desktop para que funcione con el servidor MCP, siga estos pasos. Para obtener una guía detallada, consulte la Guía del usuario de Claude Desktop .

1. Descargar Claude para escritorio
   • Disponible para Windows y macOS.
   • Para los usuarios de Linux, pueden crear un paquete Debian utilizando este script de compilación no oficial .
2. Abra la aplicación Claude Desktop y habilite el Modo de desarrollador desde la barra de menú superior izquierda.
3. Una vez habilitado, abra Configuración (también desde la barra de menú superior izquierda) y navegue hasta la Opción de desarrollador , donde encontrará el botón Editar configuración .
4. Abra el archivo de configuración y edite el siguiente archivo:
   • En macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • En Windows: %APPDATA%/Claude/claude_desktop_config.json
   • En Linux: ~/.config/Claude/claude_desktop_config.json
   { "mcpServers": { "actors-mcp-server": { "command": "npx", "args": ["-y", "@apify/actors-mcp-server"], "env": { "APIFY_TOKEN": "your-apify-token" } } } }

   Alternativamente, puede utilizar el argumento actors para seleccionar uno o más actores de Apify:

   { "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" } } } }
5. Reiniciar Claude Desktop
   • Salga completamente de Claude Desktop (asegúrese de que no esté simplemente minimizado o cerrado).
   • Reinicie Claude Desktop.
   • Busque el ícono 🔌 para confirmar que el servidor Actors MCP está conectado.
6. Abra el chat de Claude Desktop y pregunte "¿Qué actores de Apify puedo usar?"
7. EjemplosPuedes pedirle a Claude que realice tareas como:
   Find and analyze recent research papers about LLMs. Find the top 10 best Italian restaurants in San Francisco. Find and analyze the Instagram profile of The Rock.

Código VS

Para la instalación con un solo clic, haga clic en uno de los botones de instalación a continuación:

Instalación manual

Puedes instalar manualmente el servidor Apify MCP en VS Code. Primero, haz clic en uno de los botones de instalación en la parte superior de esta sección para instalarlo con un solo clic.

Como alternativa, agrega el siguiente bloque JSON a tu archivo de configuración de usuario (JSON) en VS Code. Puedes hacerlo presionando Ctrl + Shift + P y escribiendo Preferences: Open User Settings (JSON) .

Opcionalmente, puede agregarlo a un archivo llamado .vscode/mcp.json en su espacio de trabajo; simplemente omita la clave mcp {} de nivel superior. Esto le permitirá compartir la configuración con otros.

Si desea especificar qué actores cargar, puede agregar el argumento --actors :

Código VS

Para la instalación con un solo clic, haga clic en uno de los botones de instalación a continuación:

Instalación manual

Puedes instalar manualmente el servidor Apify MCP en VS Code. Primero, haz clic en uno de los botones de instalación en la parte superior de esta sección para instalarlo con un solo clic.

Como alternativa, agrega el siguiente bloque JSON a tu archivo de configuración de usuario (JSON) en VS Code. Puedes hacerlo presionando Ctrl + Shift + P y escribiendo Preferences: Open User Settings (JSON) .

Opcionalmente, puede agregarlo a un archivo llamado .vscode/mcp.json en su espacio de trabajo; simplemente omita la clave mcp {} de nivel superior. Esto le permitirá compartir la configuración con otros.

Si desea especificar qué actores cargar, puede agregar el argumento --actors :

Depuración del paquete NPM @apify/actors-mcp-server con @modelcontextprotocol/inspector

Para depurar el servidor, utilice la herramienta MCP Inspector :

Instalación mediante herrería

Para instalar Apify Actors MCP Server para Claude Desktop automáticamente a través de Smithery :

Clientes de Stdio

Cree un archivo de entorno .env con el siguiente contenido:

En el directorio examples , puede encontrar un cliente de ejemplo para interactuar con el servidor a través de entrada/salida estándar (stdio):

• clientStdio.ts Este script de cliente inicia el servidor MCP con dos actores especificados. A continuación, llama a la herramienta apify/rag-web-browser con una consulta e imprime el resultado. Muestra cómo conectarse al servidor MCP, listar las herramientas disponibles y llamar a una herramienta específica mediante el transporte stdio.
  node dist/examples/clientStdio.js

👷🏼 Desarrollo

Prerrequisitos

• Node.js (v18 o superior)
• Python 3.9 o superior

Cree un archivo de entorno .env con el siguiente contenido:

Construya el paquete actor-mcp-server:

Cliente local (SSE)

Para probar el servidor con el transporte SSE, puede usar el script examples/clientSse.ts : Actualmente, el cliente Node.js no permite establecer una conexión con un servidor remoto con encabezados personalizados. Debe cambiar la URL a la de su servidor local en el script.

Depuración

Dado que los servidores MCP operan con la entrada/salida estándar (stdio), la depuración puede ser complicada. Para una mejor experiencia de depuración, utilice el Inspector MCP .

Puede iniciar el Inspector MCP a través de npm con este comando:

Al iniciarse, el Inspector mostrará una URL a la que podrá acceder en su navegador para comenzar a depurar.

ⓘ Limitaciones y retroalimentación

El esquema de entrada del actor se procesa para que sea compatible con la mayoría de los clientes MCP, cumpliendo con los estándares de esquema JSON . El procesamiento incluye:

• Las descripciones se truncan a 500 caracteres (como se define en MAX_DESCRIPTION_LENGTH ).
• Los campos de enumeración se truncan a una longitud combinada máxima de 200 caracteres para todos los elementos (como se define en ACTOR_ENUM_MAX_LENGTH ).
• Los campos obligatorios están marcados explícitamente con un prefijo "REQUERIDO" en sus descripciones para compatibilidad con marcos que pueden no manejar el esquema JSON correctamente.
• Las propiedades anidadas se crean para casos especiales, como la configuración de proxy y las fuentes de listas de solicitudes, para garantizar una estructura de entrada correcta.
• Los tipos de elementos de la matriz se infieren cuando no están definidos explícitamente en el esquema, utilizando un orden de prioridad: tipo explícito en elementos > tipo de relleno previo > tipo de valor predeterminado > tipo de editor.
• Se agregan valores de enumeración y ejemplos a las descripciones de propiedades para garantizar la visibilidad incluso si el cliente no admite totalmente el esquema JSON.

La memoria de cada actor está limitada a 4 GB. Los usuarios gratuitos tienen un límite de 8 GB; se deben asignar 128 MB para ejecutar Actors-MCP-Server .

Si necesita otras funciones o tiene algún comentario, envíe un problema en Apify Console para informarnos.

Hoja de ruta (marzo de 2025)

• Agregue el conjunto de datos de Apify y el almacén de valores clave como recursos.
• Agregue herramientas como registros de actor y ejecuciones de actor para la depuración.

🐛 Solución de problemas

• Asegúrese de tener el node instalado ejecutando node -v
• Asegúrese de tener configurada la variable de entorno APIFY_TOKEN
• Utilice siempre la última versión del servidor MCP configurando @apify/actors-mcp-server@latest

📚 Más información

• Protocolo de contexto modelo
• ¿Qué son los agentes de IA?
• ¿Qué es MCP y por qué es importante?
• Cliente Tester MCP
• Flujo de trabajo del agente de IA: creación de un agente para consultar conjuntos de datos de Apify
• Guía de desarrollo de clientes MCP
• Cómo crear y monetizar un agente de IA en Apify