actors-mcp-server

Сервер протокола контекста модели Apify (MCP)

Реализация сервера MCP для всех субъектов Apify . Этот сервер обеспечивает взаимодействие с одним или несколькими субъектами Apify, которые могут быть определены в конфигурации сервера MCP.

Сервер можно использовать двумя способами:

• 🇦 MCP Server Actor – HTTP-сервер, доступный через Server-Sent Events (SSE), см. руководство
• ⾕ MCP Server Stdio – Локальный сервер доступен через стандартный ввод/вывод (stdio), см. руководство

Вы также можете взаимодействовать с сервером MCP, используя пользовательский интерфейс в виде чата с помощью 💬 Tester MCP Client

🎯 Что делает сервер Apify MCP?

MCP Server Actor позволяет помощнику AI использовать любого Apify Actor в качестве инструмента для выполнения определенной задачи. Например, он может:

• Используйте Facebook Posts Scraper для извлечения данных из публикаций Facebook с нескольких страниц/профилей.
• Используйте Google Maps Email Extractor для извлечения контактных данных из Google Maps
• Используйте Google Search Results Scraper для сбора страниц результатов поиска Google (SERP)
• Используйте Instagram Scraper для сбора данных из постов, профилей, мест, фотографий и комментариев в Instagram.
• Используйте веб-браузер RAG для поиска в Интернете, извлечения N самых популярных URL-адресов и возврата их содержимого.

Клиенты МКП

Для взаимодействия с сервером Apify MCP вы можете использовать такие клиенты MCP, как:

• Claude Desktop (поддержка только Stdio)
• Visual Studio Code (поддержка Stdio и SSE)
• LibreChat (поддержка Stdio и SSE, но без заголовка Authorization)
• Клиент Apify Tester MCP (поддержка SSE с заголовками авторизации)
• Другие клиенты на https://modelcontextprotocol.io/clients
• Больше клиентов на https://glama.ai/mcp/clients

Когда Actors интегрирован с сервером MCP, вы можете задать следующие вопросы:

• «Поиск в Интернете и обобщение последних тенденций в области агентов ИИ»
• «Найдите 10 лучших итальянских ресторанов в Сан-Франциско»
• «Найдите и проанализируйте профиль The Rock в Instagram»
• «Предоставьте пошаговое руководство по использованию протокола контекста модели с исходными URL-адресами»
• «Какие актеры Apify я могу использовать?»

На следующем изображении показано, как сервер Apify MCP взаимодействует с платформой Apify и клиентами ИИ:

С клиентом MCP Tester вы можете загружать актеров динамически, но это пока не поддерживается другими клиентами MCP. Мы также планируем добавить больше функций, см. Дорожную карту для получения более подробной информации.

🔄 Что такое протокол контекста модели?

Протокол контекста модели (MCP) позволяет приложениям ИИ (и агентам ИИ), таким как Claude Desktop, подключаться к внешним инструментам и источникам данных. MCP — это открытый протокол, который обеспечивает безопасное, контролируемое взаимодействие между приложениями ИИ, агентами ИИ и локальными или удаленными ресурсами.

Более подробную информацию можно найти на веб-сайте Model Context Protocol или в записи блога Что такое MCP и почему это важно?.

🤖 Как MCP Server связан с AI Agents?

Сервер Apify MCP предоставляет доступ к акторам Apify через протокол MCP, позволяя агентам ИИ или фреймворкам, реализующим протокол MCP, получать доступ ко всем акторам Apify в качестве инструментов для извлечения данных, веб-поиска и других задач.

Чтобы узнать больше об агентах ИИ, изучите нашу запись в блоге: Что такое агенты ИИ? и просмотрите подобранную коллекцию агентов ИИ Apify. Хотите создать и монетизировать своего собственного агента ИИ на Apify? Ознакомьтесь с нашим пошаговым руководством по созданию, публикации и монетизации агентов ИИ на платформе Apify.

🧱 Компоненты

Инструменты

Актеры

Любой актер Apify может быть использован в качестве инструмента. По умолчанию сервер предварительно настроен с указанными ниже актерами, но это можно переопределить, предоставив входные данные актера.

Сервер MCP загружает входную схему Actor и создает инструменты MCP, соответствующие Actors. Смотрите этот пример входной схемы для веб-браузера RAG .

Имя инструмента всегда должно быть полным именем Актера, например apify/rag-web-browser . Аргументы для инструмента MCP представляют входные параметры Актера. Например, для Актера apify/rag-web-browser аргументы следующие:

Вам не нужно указывать входные параметры или какой Actor вызывать; всем управляет LLM. Когда вызывается инструмент, аргументы автоматически передаются Actor от LLM. Вы можете обратиться к документации конкретного Actor для получения списка доступных аргументов.

Вспомогательные инструменты

Сервер предоставляет набор вспомогательных инструментов для обнаружения доступных Актеров и получения их данных:

• get-actor-details : извлекает документацию, входную схему и сведения о конкретном Актере.
• discover-actors : ищет соответствующих актеров по ключевым словам и возвращает их данные.

Также имеются инструменты для управления списком доступных инструментов. Однако динамическое добавление и удаление инструментов требует, чтобы клиент MCP имел возможность обновлять список инструментов (обрабатывать ToolListChangedNotificationSchema ), что обычно не поддерживается.

Вы можете попробовать эту функциональность с помощью Apify Tester MCP Client Actor. Чтобы включить ее, установите параметр enableActorAutoLoading .

• add-actor-as-tool : добавляет актера по имени в список доступных инструментов, не выполняя его, требуя согласия пользователя для последующего запуска.
• remove-actor-from-tool : удаляет актера по имени из списка доступных инструментов, когда он больше не нужен.

Подсказка и ресурсы

Сервер не предоставляет никаких ресурсов и подсказок. Мы планируем добавить набор данных Apify и хранилище ключей и значений в качестве ресурсов в будущем.

⚙️ Использование

Сервер Apify MCP можно использовать двумя способами: как субъект Apify, работающий на платформе Apify, или как локальный сервер , работающий на вашем компьютере.

🇦 MCP Сервер Актер

Резервный веб-сервер

Actor работает в режиме ожидания с HTTP-веб-сервером, который принимает и обрабатывает запросы.

Чтобы запустить сервер с акторами по умолчанию, отправьте HTTP-запрос GET с вашим токеном API Apify на следующий URL-адрес:

Также возможно запустить сервер MCP с другим набором Актеров. Для этого создайте задачу и укажите список Актеров, которых вы хотите использовать.

Затем запустите задачу в режиме ожидания с выбранными участниками:

Список всех доступных актеров можно найти в магазине Apify .

💬 Взаимодействие с сервером MCP через SSE

После запуска сервера вы можете взаимодействовать с Server-Sent Events (SSE) для отправки сообщений на сервер и получения ответов. Самый простой способ — использовать Tester MCP Client на Apify.

В настоящее время Claude Desktop не поддерживает SSE, но вы можете использовать его с транспортом Stdio; см . MCP Server на локальном хосте для получения более подробной информации. Примечание: бесплатная версия Claude Desktop может испытывать периодические проблемы с подключением к серверу.

В настройках клиента необходимо указать конфигурацию сервера:

В качестве альтернативы вы можете использовать скрипт clientSse.ts или протестировать сервер с помощью команд curl </>.

1. Инициируйте Server-Sent-Events (SSE), отправив запрос GET на следующий URL:
   curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>
   Сервер ответит sessionId , который можно использовать для отправки сообщений на сервер:
   event: endpoint data: /message?sessionId=a1b
2. Отправьте сообщение на сервер, выполнив POST-запрос с 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" } }'
   Сервер MCP запустит Actor lukaskrivka/google-maps-with-contact-details с предоставленными аргументами в качестве входных параметров. Для этого запроса POST сервер ответит:
   Accepted
3. Получите ответ. Сервер вызовет указанный Actor как инструмент, используя предоставленные параметры запроса, и передаст ответ обратно клиенту через SSE. Ответ будет возвращен как текст 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+\"...}}]}}

⾕ MCP-сервер на локальном хосте

Вы можете запустить Apify MCP Server на локальной машине, настроив его с помощью Claude Desktop или любого другого клиента MCP . Вы также можете использовать Smithery для автоматической установки сервера.

Предпосылки

• MacOS или Windows
• Должна быть установлена последняя версия Claude Desktop (или другой клиент MCP)
• Node.js (v18 или выше)
• API-токен Apify ( APIFY_TOKEN )

Убедитесь, что у вас правильно установлены node и npx :

Если нет, следуйте этому руководству по установке Node.js: Загрузка и установка Node.js и npm .

Клод Десктоп

Чтобы настроить Claude Desktop для работы с сервером MCP, выполните следующие шаги. Для подробного руководства обратитесь к Claude Desktop User Guide или посмотрите видеоурок .

1. Скачать Клод для рабочего стола
   • Доступно для Windows и macOS.
   • Пользователи Linux могут собрать пакет Debian, используя этот неофициальный скрипт сборки .
2. Откройте приложение Claude Desktop и включите режим разработчика в верхней левой строке меню.
3. После включения откройте «Настройки» (также из верхней левой панели меню) и перейдите в раздел « Параметры разработчика» , где вы найдете кнопку «Изменить конфигурацию» .
4. Откройте файл конфигурации и отредактируйте следующий файл:
   • На macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • В Windows: %APPDATA%/Claude/claude_desktop_config.json
   • В 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" } } } }

   В качестве альтернативы вы можете использовать аргумент actors для выбора одного или нескольких актеров 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. Перезагрузить рабочий стол Клода
   • Полностью закройте Claude Desktop (убедитесь, что он не просто свернут или закрыт).
   • Перезагрузите Claude Desktop.
   • Найдите значок 🔌, чтобы подтвердить, что сервер Actors MCP подключен.
6. Откройте чат Claude Desktop и спросите: «Какие актеры Apify я могу использовать?»
7. ПримерыВы можете попросить Клода выполнить такие задания, как:
   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.

Код VS

Для установки в один клик нажмите одну из кнопок установки ниже:

Ручная установка

Вы можете вручную установить Apify MCP Server в VS Code. Сначала нажмите одну из кнопок установки в верхней части этого раздела для установки в один клик.

В качестве альтернативы добавьте следующий блок JSON в файл настроек пользователя (JSON) в VS Code. Это можно сделать, нажав Ctrl + Shift + P и введя Preferences: Open User Settings (JSON) .

При желании вы можете добавить его в файл .vscode/mcp.json в вашем рабочем пространстве — просто опустите ключ верхнего уровня mcp {} . Это позволит вам поделиться конфигурацией с другими.

Если вы хотите указать, какие актеры следует загрузить, вы можете добавить аргумент --actors :

Код VS

Для установки в один клик нажмите одну из кнопок установки ниже:

Ручная установка

Вы можете вручную установить Apify MCP Server в VS Code. Сначала нажмите одну из кнопок установки в верхней части этого раздела для установки в один клик.

В качестве альтернативы добавьте следующий блок JSON в файл настроек пользователя (JSON) в VS Code. Это можно сделать, нажав Ctrl + Shift + P и введя Preferences: Open User Settings (JSON) .

При желании вы можете добавить его в файл .vscode/mcp.json в вашем рабочем пространстве — просто опустите ключ верхнего уровня mcp {} . Это позволит вам поделиться конфигурацией с другими.

Если вы хотите указать, какие актеры следует загрузить, вы можете добавить аргумент --actors :

Отладка пакета NPM @apify/actors-mcp-server с помощью @modelcontextprotocol/inspector

Для отладки сервера используйте инструмент MCP Inspector :

Установка через Smithery

Чтобы автоматически установить Apify Actors MCP Server для Claude Desktop через Smithery :

Клиенты Stdio

Создайте файл среды .env со следующим содержимым:

В каталоге examples вы можете найти пример клиента для взаимодействия с сервером через стандартный ввод/вывод (stdio):

• clientStdio.ts Этот клиентский скрипт запускает сервер MCP с двумя указанными Actors. Затем он вызывает инструмент apify/rag-web-browser с запросом и выводит результат. Он демонстрирует, как подключиться к серверу MCP, составить список доступных инструментов и вызвать определенный инструмент с помощью транспорта stdio.
  node dist/examples/clientStdio.js

👷🏼 Разработка

Предпосылки

• Node.js (v18 или выше)
• Python 3.9 или выше

Создайте файл среды .env со следующим содержимым:

Соберите пакет actor-mcp-server:

Локальный клиент (SSE)

Для тестирования сервера с транспортом SSE можно использовать скрипт examples/clientSse.ts : В настоящее время клиент Node.js не поддерживает установление соединения с удаленным сервером с пользовательскими заголовками. Вам необходимо изменить URL на URL вашего локального сервера в скрипте.

Отладка

Поскольку серверы MCP работают через стандартный ввод/вывод (stdio), отладка может быть сложной. Для лучшего опыта отладки используйте MCP Inspector .

Вы можете запустить MCP Inspector через npm с помощью этой команды:

После запуска Инспектор отобразит URL-адрес, к которому вы можете перейти в своем браузере, чтобы начать отладку.

ⓘ Ограничения и обратная связь

Схема ввода Actor обрабатывается для совместимости с большинством клиентов MCP, придерживаясь стандартов JSON Schema . Обработка включает:

• Описания обрезаются до 500 символов (как определено в MAX_DESCRIPTION_LENGTH ).
• Поля перечисления усекаются до максимальной общей длины 200 символов для всех элементов (как определено в ACTOR_ENUM_MAX_LENGTH ).
• Обязательные поля явно помечены префиксом «REQUIRED» в своих описаниях для совместимости с фреймворками, которые могут некорректно обрабатывать схему JSON.
• Вложенные свойства создаются для особых случаев, таких как конфигурация прокси-сервера и источники списка запросов, чтобы обеспечить правильную структуру входных данных.
• Типы элементов массива выводятся, если они явно не определены в схеме, с использованием порядка приоритетов: явный тип в элементах > тип предварительного заполнения > тип значения по умолчанию > тип редактора.
• Значения перечисления и примеры добавляются к описаниям свойств, чтобы обеспечить видимость, даже если клиент не полностью поддерживает схему JSON.

Память для каждого Актера ограничена 4 ГБ. Бесплатные пользователи имеют ограничение в 8 ГБ, 128 МБ необходимо выделить для запуска Actors-MCP-Server .

Если вам нужны другие функции или у вас есть какие-либо отзывы, отправьте сообщение о проблеме в консоли Apify, чтобы сообщить нам.

🚀 Дорожная карта (март 2025 г.)

• Добавьте набор данных Apify и хранилище «ключ-значение» в качестве ресурсов.
• Добавьте такие инструменты, как журналы Actor и запуски Actor для отладки.

🐛 Устранение неполадок

• Убедитесь, что у вас установлен node , запустив node -v
• Убедитесь, что у вас установлена переменная среды APIFY_TOKEN
• Всегда используйте последнюю версию сервера MCP, установив @apify/actors-mcp-server@latest

📚 Узнать больше

• Модель контекстного протокола
• Что такое агенты ИИ?
• Что такое MCP и почему это важно?
• Как использовать MCP с Apify Actors
• Тестер MCP Клиент
• Рабочий процесс агента ИИ: создание агента для запроса наборов данных Apify
• Руководство по разработке клиента MCP
• Как создать и монетизировать ИИ-агента на Apify