actors-mcp-server

Apify 模型上下文协议 (MCP) 服务器

为所有Apify Actors实现一个 MCP 服务器。该服务器支持与一个或多个 Apify Actors 进行交互，这些 Actors 可以在 MCP 服务器配置中定义。

该服务器可以以两种方式使用：

• 🇦 MCP 服务器 Actor – 可通过服务器发送事件 (SSE) 访问的 HTTP 服务器，请参阅指南
• ⾕ MCP Server Stdio – 可通过标准输入/输出 (stdio) 访问的本地服务器，请参阅指南

您还可以使用类似聊天的 UI 与 MCP 服务器进行交互，使用 💬 Tester MCP Client

🎯 Apify MCP 服务器做什么？

MCP 服务器 Actor 允许 AI 助手使用任意Apify Actor作为工具来执行特定任务。例如，它可以：

• 使用Facebook Posts Scraper从多个页面/个人资料中提取 Facebook 帖子数据
• 使用Google 地图电子邮件提取器提取 Google 地图联系人详细信息
• 使用Google 搜索结果抓取工具抓取 Google 搜索引擎结果页面 (SERP)
• 使用Instagram Scraper抓取 Instagram 帖子、个人资料、地点、照片和评论
• 使用RAG Web 浏览器搜索网络，抓取排名前 N 的 URL，并返回其内容

MCP 客户端

要与 Apify MCP 服务器交互，您可以使用 MCP 客户端，例如：

• Claude Desktop （仅支持 Stdio）
• Visual Studio Code （支持 Stdio 和 SSE）
• LibreChat （支持 Stdio 和 SSE，但没有授权标头）
• Apify Tester MCP 客户端（带有授权标头的 SSE 支持）
• 其他客户端： https://modelcontextprotocol.io/clients
• 更多客户信息请访问https://glama.ai/mcp/clients

当您将 Actors 与 MCP 服务器集成时，您可以询问：

• “搜索网络并总结有关人工智能代理的最新趋势”
• “寻找旧金山十大最佳意大利餐厅”
• “查找并分析巨石强森的 Instagram 个人资料”
• “提供使用带有源 URL 的模型上下文协议的分步指南”
• “我可以使用哪些 Apify Actors？”

下图展示了 Apify MCP 服务器与 Apify 平台和 AI 客户端的交互方式：

使用 MCP Tester 客户端，您可以动态加载 Actor，但其他 MCP 客户端尚不支持此功能。我们还计划添加更多功能，详情请参阅路线图。

🔄 什么是模型上下文协议？

模型上下文协议 (MCP) 允许 AI 应用程序（以及 AI 代理）（例如 Claude Desktop）连接到外部工具和数据源。MCP 是一种开放协议，支持 AI 应用程序、AI 代理以及本地或远程资源之间安全、可控的交互。

有关更多信息，请参阅模型上下文协议网站或博客文章什么是 MCP 以及它为什么重要？ 。

🤖 MCP 服务器与 AI 代理有何关系？

Apify MCP 服务器通过 MCP 协议公开 Apify 的 Actors，允许实现 MCP 协议的 AI Agent 或框架访问所有 Apify Actors，作为数据提取、网络搜索和其他任务的工具。

要了解更多关于 AI 代理的信息，请阅读我们的博客文章：什么是 AI 代理？并浏览 Apify 精选的AI 代理合集。有兴趣在 Apify 上构建自己的 AI 代理并实现盈利吗？查看我们的分步指南，了解如何在 Apify 平台上创建、发布和实现 AI 代理盈利。

🧱 组件

工具

演员

任何Apify Actor均可用作工具。默认情况下，服务器已预先配置了以下指定的 Actor，但可以通过提供 Actor 输入来覆盖此配置。

MCP 服务器加载 Actor 输入架构，并创建与 Actor 对应的 MCP 工具。请参阅RAG Web 浏览器的输入架构示例 。

工具名称必须始终是完整的 Actor 名称，例如apify/rag-web-browser 。MCP 工具的参数表示 Actor 的输入参数。例如，对于apify/rag-web-browser Actor，其参数为：

您无需指定输入参数或调用哪个 Actor；所有操作均由 LLM 管理。调用工具时，LLM 会自动将参数传递给 Actor。您可以参考特定 Actor 的文档，了解可用参数的列表。

辅助工具

服务器提供了一组辅助工具来发现可用的参与者并检索其详细信息：

• get-actor-details ：检索有关特定 Actor 的文档、输入模式和详细信息。
• discover-actors ：使用关键字搜索相关的演员并返回他们的详细信息。

还有一些工具可以管理可用的工具列表。但是，动态添加和删除工具需要 MCP 客户端具备更新工具列表（处理ToolListChangedNotificationSchema ）的能力，而这通常不受支持。

您可以使用Apify Tester MCP 客户端Actor 尝试此功能。要启用此功能，请设置enableAddingActors参数。

• add-actor-as-tool ：按名称将 Actor 添加到可用工具列表中但不执行它，需要用户同意稍后运行。
• remove-actor-from-tool ：当不再需要某个 Actor 时，从可用工具列表中按名称将其删除。

提示和资源

服务器不提供任何资源和提示。我们计划在未来添加Apify 的数据集和键值存储作为资源。

⚙️ 使用方法

Apify MCP 服务器可以通过两种方式使用：作为在 Apify 平台上运行的 Apify Actor或作为在您的机器上运行的本地服务器。

🇦 MCP 服务器 Actor

备用 Web 服务器

Actor 以待机模式运行，并带有一个接收和处理请求的 HTTP Web 服务器。

要使用默认 Actors 启动服务器，请将带有Apify API 令牌的HTTP GET 请求发送到以下 URL：

您也可以使用不同的 Actor 集合来启动 MCP 服务器。为此，请创建一个任务并指定要使用的 Actor 列表。

然后，使用选定的 Actors 在待机模式下运行任务：

您可以在Apify Store中找到所有可用演员的列表。

💬 通过 SSE 与 MCP 服务器交互

服务器运行后，您可以与服务器发送事件 (SSE) 进行交互，向服务器发送消息并接收响应。最简单的方法是使用 Apify 上的Tester MCP 客户端。

Claude Desktop目前不支持 SSE，但您可以将其与 Stdio 传输一起使用；有关更多详细信息，请参阅本地主机上的 MCP 服务器。注意：Claude Desktop 的免费版本可能会遇到与服务器的间歇性连接问题。

在客户端设置中，需要提供服务器配置：

或者，您可以使用clientSse.ts脚本或使用curl </> 命令测试服务器。

1. 通过向以下 URL 发送 GET 请求来启动服务器发送事件 (SSE)：
   curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>
   服务器将使用sessionId进行响应，您可以使用该 sessionId 向服务器发送消息：
   event: endpoint data: /message?sessionId=a1b
2. 通过使用sessionId发出 POST 请求向服务器发送消息：
   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 服务器

您可以通过 Claude Desktop 或任何其他MCP 客户端在本地计算机上配置 Apify MCP 服务器来运行它。您也可以使用Smithery自动安装服务器。

先决条件

• MacOS 或 Windows
• 必须安装最新版本的 Claude Desktop（或其他 MCP 客户端）
• Node.js （v18 或更高版本）
• Apify API 令牌（ APIFY_TOKEN ）

确保已正确安装node和npx ：

如果没有，请按照本指南安装 Node.js：下载并安装 Node.js 和 npm 。

克劳德桌面

要配置 Claude Desktop 与 MCP 服务器配合使用，请按照以下步骤操作。有关详细指南，请参阅Claude Desktop 用户指南或观看视频教程。

1. 下载 Claude 桌面版
   • 适用于 Windows 和 macOS。
   • 对于 Linux 用户，您可以使用这个非官方的构建脚本来构建 Debian 包。
2. 打开 Claude 桌面应用程序并从左上角的菜单栏启用开发者模式。
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 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" } } } }
5. 重启Claude桌面
   • 完全退出 Claude Desktop（确保它不仅仅是最小化或关闭）。
   • 重新启动 Claude Desktop。
   • 查找🔌图标以确认 Actors MCP 服务器已连接。
6. 打开 Claude 桌面聊天并询问“我可以使用哪些 Apify Actors？”
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 代码

对于一键安装，请单击以下安装按钮之一：

手动安装

您可以在 VS Code 中手动安装 Apify MCP 服务器。首先，点击本节顶部的安装按钮之一，即可一键安装。

或者，在 VS Code 中，将以下 JSON 块添加到“用户设置 (JSON)”文件中。您可以按下Ctrl + Shift + P并输入Preferences: Open User Settings (JSON)来执行此操作。

或者，您可以将其添加到工作区中名为.vscode/mcp.json的文件中 - 只需省略顶层mcp {}键即可。这样您就可以与其他人共享配置。

如果要指定加载哪些 Actors，可以添加--actors参数：

VS 代码

对于一键安装，请单击以下安装按钮之一：

手动安装

您可以在 VS Code 中手动安装 Apify MCP 服务器。首先，点击本节顶部的安装按钮之一，即可一键安装。

或者，在 VS Code 中，将以下 JSON 块添加到“用户设置 (JSON)”文件中。您可以按下Ctrl + Shift + P并输入Preferences: Open User Settings (JSON)来执行此操作。

或者，您可以将其添加到工作区中名为.vscode/mcp.json的文件中 - 只需省略顶层mcp {}键即可。这样您就可以与其他人共享配置。

如果要指定加载哪些 Actors，可以添加--actors参数：

使用 @modelcontextprotocol/inspector 调试 NPM 包 @apify/actors-mcp-server

要调试服务器，请使用MCP Inspector工具：

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Apify Actors MCP 服务器：

Stdio 客户端

创建一个环境文件.env ，内容如下：

在examples目录中，您可以找到一个示例客户端，通过标准输入/输出（stdio）与服务器交互：

• clientStdio.ts此客户端脚本使用两个指定的 Actor 启动 MCP 服务器。然后，它会通过查询调用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 检查器。

您可以使用以下命令通过npm启动 MCP Inspector：

启动后，检查器将显示一个 URL，您可以在浏览器中访问该 URL 以开始调试。

ⓘ 限制和反馈

Actor 输入模式经过处理，兼容大多数 MCP 客户端，同时遵循JSON Schema标准。处理过程包括：

• 描述被截断为 500 个字符（如MAX_DESCRIPTION_LENGTH中所定义）。
• 所有元素的枚举字段被截断为最大总长度 200 个字符（如ACTOR_ENUM_MAX_LENGTH中所定义）。
• 必填字段在其描述中明确标有“REQUIRED”前缀，以便与可能无法正确处理 JSON 模式的框架兼容。
• 为代理配置和请求列表源等特殊情况构建嵌套属性，以确保正确的输入结构。
• 当未在架构中明确定义时，将推断数组项类型，使用优先级顺序：项中的显式类型 > 预填充类型 > 默认值类型 > 编辑器类型。
• 将枚举值和示例添加到属性描述中，以确保即使客户端不完全支持 JSON 模式也能看到。

每个 Actor 的内存限制为 4GB。免费用户限制为 8GB，运行Actors-MCP-Server需要分配 128MB 内存。

如果您需要其他功能或有任何反馈，请在 Apify 控制台中提交问题让我们知道。

🚀 路线图（2025 年 3 月）

• 添加 Apify 的数据集和键值存储作为资源。
• 添加 Actor 日志和 Actor 运行等工具以供调试。

🐛 故障排除

• 通过运行node -v确保已安装node
• 确保已设置APIFY_TOKEN环境变量
• 通过设置@apify/actors-mcp-server@latest始终使用最新版本的 MCP 服务器

📚 了解更多

• 模型上下文协议
• 什么是 AI 代理？
• 什么是 MCP？它为何重要？
• 如何将 MCP 与 Apify Actors 结合使用
• 测试器 MCP 客户端
• AI 代理工作流程：构建代理来查询 Apify 数据集
• MCP 客户端开发指南
• 如何在 Apify 上构建 AI 代理并实现盈利