olostep-mcp

Olostep MCP 服务

Docker Hub npm 版本 许可证：ISC

这是一个模型上下文协议（MCP）服务实现，可与 Olostep 集成，提供网页抓取、内容提取和搜索功能。 要设置 Olostep MCP 服务，你需要 API 密钥。你可以在 Olostep 网站注册获取 API 密钥。

功能

• 抓取网站内容，支持 HTML、Markdown、JSON 或纯文本格式（可选解析器）
• 基于解析器的网页搜索，并提供结构化结果
• AI 答案，附带引用，并可选择输出 JSON 格式
• 批量抓取最多 10k 个 URL
• 从起始 URL 开始自主爬取网站
• 发现并映射网站 URL（支持包含/排除筛选器）
• 针对特定国家/地区的请求路由，以获取地理定位内容
• 可配置 JavaScript 密集型网站的等待时间
• 全面的错误处理和报告
• 简单的 API 密钥配置

安装

有多种方式可连接到 Olostep MCP 服务。请选择最适合你工作流的方式。

一键安装

连接到托管服务，并使用你的 Olostep 账户（OAuth）登录。无需 API 密钥或本地设置。

也可以在终端中运行：

# Claude Code
claude mcp add --transport http olostep https://mcp.olostep.com/mcp

# Gemini CLI (prompts for your API key)
gemini extensions install https://github.com/olostep/olostep-mcp-server

其他客户端请参阅客户端设置。

☁️ 远程端点（推荐）

最简单的方式——无需本地安装。直接连接到我们托管的 MCP 服务：

https://mcp.olostep.com/mcp

使用 Olostep API 密钥，通过 Authorization 标头中的 Bearer 令牌进行身份验证。配置示例请参阅下方的客户端设置部分。

🐳 Docker Hub

拉取并运行官方 Docker 镜像：

docker pull olostep/mcp-server

docker run -i --rm \
  -e OLOSTEP_API_KEY="your-api-key" \
  olostep/mcp-server

🔧 本地 Docker 构建

如果你希望自行从源代码构建镜像：

git clone https://github.com/olostep/olostep-mcp-server.git
cd olostep-mcp-server
npm install
npm run build
docker build -t olostep/mcp-server:local .

docker run -i --rm -e OLOSTEP_API_KEY="your-api-key" olostep/mcp-server:local

📦 npx

使用 npx 运行，无需安装：

env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp

在 Windows（PowerShell）上：

$env:OLOSTEP_API_KEY = "your-api-key"; npx -y olostep-mcp

在 Windows（CMD）上：

set OLOSTEP_API_KEY=your-api-key && npx -y olostep-mcp

也可以全局安装：

npm install -g olostep-mcp

客户端设置

Gemini CLI

在 Gemini CLI 中安装 Olostep 扩展（需要 Olostep API 密钥）：

gemini extensions install https://github.com/olostep/olostep-mcp-server

通过 Gemini CLI 的敏感扩展设置配置你的 API 密钥：

gemini extensions config olostep OLOSTEP_API_KEY

Gemini CLI 会将此值存储在系统钥匙串中。重启 Gemini CLI，然后验证扩展和 MCP 服务：

gemini extensions list
gemini mcp list

如果遇到身份验证错误，请重新配置密钥。如果遇到连接错误，请重启 Gemini CLI 并运行 gemini mcp list。详情请参阅官方 Gemini CLI 扩展文档。

Cursor

最简单的方法是使用远程端点。在项目根目录中创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

替代方案（本地）： 前往 Cursor Settings > Features > MCP Servers，点击“+ Add New MCP Server”：

• 名称： olostep
• 类型： command
• 命令： env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-server-olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

替代方案（Docker）：

{
  "mcpServers": {
    "olostep": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OLOSTEP_API_KEY=YOUR_API_KEY_HERE",
        "olostep/mcp-server"
      ]
    }
  }
}

也可以在设备终端中通过 Smithery CLI 安装：

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

Claude Code

将远程端点添加到 Claude Code MCP 配置中：

{
  "mcpServers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

替代方案（本地）：

{
  "mcpServers": {
    "olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Windsurf

将以下内容添加到 ./codeium/windsurf/model_config.json：

{
  "mcpServers": {
    "olostep": {
      "serverUrl": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

替代方案（本地）：

{
  "mcpServers": {
    "mcp-server-olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Cline

将以下内容添加到 cline_mcp_settings.json（Cline → MCP Servers → Configure）：

{
  "mcpServers": {
    "olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline 也可以为你完成设置：让它从此代码仓库安装 MCP 服务，它会按照 llms-install.md 操作。

VS Code

将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "olostep": {
      "type": "http",
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

替代方案（本地）：

{
  "servers": {
    "olostep": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

GitHub Copilot CLI

在 Copilot CLI 中，运行 /mcp add 并输入：

• 名称： olostep
• 类型： HTTP
• URL： https://mcp.olostep.com/mcp
• 标头： 留空

按 Ctrl+S 保存，然后在提示时使用你的 Olostep 账户登录（OAuth）。使用 /mcp show olostep 检查连接。

这会将以下内容写入 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "olostep": {
      "type": "http",
      "url": "https://mcp.olostep.com/mcp",
      "tools": ["*"]
    }
  }
}

Zed

将以下内容添加到 Zed 的 settings.json：

{
  "context_servers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

替代方案（扩展）： Olostep Zed 扩展会运行本地服务，并在 Zed 的设置界面中请求你的 API 密钥。

Metorial

选项 1：一键安装（推荐）

1. 打开 Metorial 控制面板
2. 前往 MCP Servers 目录
3. 搜索“Olostep”
4. 点击“Install”并输入你的 API 密钥

选项 2：手动配置

将以下内容添加到 Metorial MCP 服务配置中：

{
  "olostep": {
    "command": "npx",
    "args": ["-y", "olostep-mcp"],
    "env": {
      "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
    }
  }
}

随后即可在 Metorial AI 聊天中使用 Olostep 工具。

配置

环境变量

• OLOSTEP_API_KEY：你的 Olostep API 密钥（必需）
• ORBIT_KEY：用于通过 Orbit 路由请求的可选密钥。

可用工具

1. 抓取网站（scrape_website）

从单个 URL 提取内容。支持多种格式和 JavaScript 渲染。

{
  "name": "scrape_website",
  "arguments": {
    "url_to_scrape": "https://example.com",
    "output_format": "markdown",
    "country": "US",
    "wait_before_scraping": 1000,
    "parser": "@olostep/amazon-it-product"
  }
}

参数：

• url_to_scrape：要抓取的网站 URL（必需）
• output_format：选择格式（html、markdown、json 或 text）——默认值：markdown
• country：可选的国家/地区代码（例如 US、GB、CA），用于按地理位置抓取
• wait_before_scraping：抓取前的等待时间，单位为毫秒（0-10000）
• parser：用于专门提取的可选解析器 ID

响应（示例）：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"id\": \"scrp_...\",\n  \"url\": \"https://example.com\",\n  \"markdown_content\": \"# ...\",\n  \"html_content\": null,\n  \"json_content\": null,\n  \"text_content\": null,\n  \"status\": \"succeeded\",\n  \"timestamp\": \"2025-11-14T12:34:56Z\",\n  \"screenshot_hosted_url\": null,\n  \"page_metadata\": { }\n}"
    }
  ]
}

2. 搜索网页（search_web）

根据给定查询搜索网页，并获取结构化结果（非 AI，基于解析器）。

{
  "name": "search_web",
  "arguments": {
    "query": "your search query",
    "country": "US"
  }
}

参数：

• query：搜索查询（必需）
• country：用于本地化结果的可选国家/地区代码（默认值：US）

响应：

• 表示基于解析器的结果的结构化 JSON（作为文本）

3. 答案（AI）（answers）

搜索网页，并按照你指定的 JSON 结构返回 AI 生成的答案，以及来源和引文。

{
  "name": "answers",
  "arguments": {
    "task": "Who are the top 5 competitors to Acme Inc. in the EU?",
    "json": "Return a list of the top 5 competitors with name and homepage URL"
  }
}

参数：

• task：使用网页数据回答的问题或执行的任务（必需）
• json：可选的 JSON 架构/对象，或对所需输出结构的简短说明

响应包含：

• answer_id、object、task、result（若已提供，则为 JSON）、sources、created

4. 批量抓取 URL（batch_scrape_urls）

同时抓取最多 10k 个 URL，非常适合大规模数据提取。

{
  "name": "batch_scrape_urls",
  "arguments": {
    "urls_to_scrape": [
      {"url": "https://example.com/a", "custom_id": "a"},
      {"url": "https://example.com/b", "custom_id": "b"}
    ],
    "output_format": "markdown",
    "country": "US",
    "wait_before_scraping": 500,
    "parser": "@olostep/amazon-it-product"
  }
}

响应包含：

• batch_id、status、total_urls、created_at、formats、country、parser、urls

5. 创建爬取任务（create_crawl）

启动一次异步爬取任务，通过跟踪链接自主发现并抓取整个网站。返回一个 crawl_id——爬取任务将在后台运行，且不会在此次响应中返回内容。然后，必须使用该 crawl_id 调用 get_crawl_results，以轮询状态并获取已抓取的页面（与 batch_scrape_urls + get_batch_results 相同的两步流程）。

{
  "name": "create_crawl",
  "arguments": {
    "start_url": "https://example.com/docs",
    "max_pages": 25,
    "output_format": "markdown",
    "country": "US",
    "parser": "@olostep/doc-parser"
  }
}

响应包括：

• crawl_id、object、status、start_url、max_pages、created、formats、country、parser

请将此调用与 get_crawl_results 配合使用——不要将 crawl_id 传给 get_batch_results（爬取任务和批处理是独立的资源）。

6. 创建映射（create_map）

获取网站上的所有 URL。提取所有 URL，用于发现和分析。

{
  "name": "create_map",
  "arguments": {
    "website_url": "https://example.com",
    "search_query": "blog",
    "top_n": 200,
    "include_url_patterns": ["/blog/**"],
    "exclude_url_patterns": ["/admin/**"]
  }
}

响应包括：

• map_id、object、url、total_urls、urls、search_query、top_n

7. 获取网页内容（get_webpage_content）

以简洁的 Markdown 格式获取网页内容，并支持 JavaScript 渲染。

{
  "name": "get_webpage_content",
  "arguments": {
    "url_to_scrape": "https://example.com",
    "wait_before_scraping": 1000,
    "country": "US"
  }
}

参数：

• url_to_scrape：要抓取的网页 URL（必填）
• wait_before_scraping：开始抓取前等待的时间（毫秒，默认值：0）
• country：发起请求时使用的住宅代理所在国家/地区（例如 US、CA、GB）（可选）

响应：

{
  "content": [
    {
      "type": "text",
      "text": "# Example Website\n\nThis is the markdown content of the webpage..."
    }
  ]
}

8. 获取网站 URL（get_website_urls）

搜索并获取网站上的相关 URL，并按与查询的相关性排序。

{
  "name": "get_website_urls",
  "arguments": {
    "url": "https://example.com",
    "search_query": "your search term"
  }
}

参数：

• url：要映射的网站 URL（必填）
• search_query：用于对 URL 排序的搜索查询（必填）

响应：

{
  "content": [
    {
      "type": "text",
      "text": "Found 42 URLs matching your query:\n\nhttps://example.com/page1\nhttps://example.com/page2\n..."
    }
  ]
}

9. 获取批处理结果（get_batch_results）

使用 batch_id 获取先前提交的批量抓取任务的结果。

{
  "name": "get_batch_results",
  "arguments": {
    "batch_id": "batch_abc123"
  }
}

参数：

• batch_id：batch_scrape_urls 返回的批处理 ID（必填）

响应包括：

• batch_id、status（processing 或 completed）、total_urls、completed_urls、items（包含每个 URL 抓取结果的数组，字段包括 url、custom_id、markdown_content、html_content、json_content、text_content、status、page_metadata）

10. 获取爬取结果（get_crawl_results）

获取通过 create_crawl 启动的异步爬取任务的状态和已抓取页面。这是 create_crawl 必须配套使用的工具——create_crawl 只会启动任务并返回 crawl_id；要获取发现的页面及其内容，需使用此工具。

{
  "name": "get_crawl_results",
  "arguments": {
    "crawl_id": "crawl_abc123",
    "formats": ["markdown"],
    "items_limit": 20,
    "cursor": 0
  }
}

参数：

• crawl_id：create_crawl 返回的爬取 ID（必填）
• formats：要获取的每个页面的格式数组——markdown、html、json、text（默认值：["markdown"]）
• items_limit：要获取内容的最大页面数，范围为 1–100（默认值：20）
• cursor：已发现页面列表中的分页游标（默认值：0）
• search_query：可选过滤条件，用于按与查询的相关性对页面排序或筛选

响应包括：

• 进行中： crawl_id、status（in_progress）、pages_completed、pages_total，以及提示你约 10 秒后再次调用的 message。
• 已完成： crawl_id、status（completed）、pages_returned、next_cursor、has_more，以及 pages 数组，其中每个条目均包含 url、custom_id 和请求的内容字段（markdown_content、html_content、json_content、text_content）。

错误处理

该服务提供完善的错误处理：

• 针对 API 问题的详细错误消息
• 网络错误报告
• 身份验证失败处理
• 速率限制信息

错误响应示例：

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Olostep API Error: 401 Unauthorized. Details: {\"error\":\"Invalid API key\"}"
    }
  ]
}

分发

Docker 镜像

MCP 服务提供 Docker 镜像：

• Docker Hub： [olostep/mcp-server](https://hub.docker.com/r/olostep/mcp-server)
• 官方 Docker MCP 注册表： mcp/olostep（即将推出——通过签名和 SBOM 增强安全性）
• GitHub Container Registry： ghcr.io/olostep/olostep-mcp-server

Docker Desktop MCP 工具包

Olostep MCP 服务正在添加到 Docker Desktop 官方 MCP 工具包中，这意味着用户将能够：

• 在 Docker Desktop 的 MCP 工具包界面中发现它
• 一键安装
• 通过可视化方式配置
• 将其与任何兼容 MCP 的客户端（Claude Desktop、Cursor 等）搭配使用

状态：正在向 Docker MCP Registry 提交

支持的平台

• linux/amd64
• linux/arm64

本地构建

# Clone the repository
git clone https://github.com/olostep/olostep-mcp-server.git
cd olostep-mcp-server

# Build the image
npm install
npm run build
docker build -t olostep/mcp-server .

# Run locally
docker run -i --rm -e OLOSTEP_API_KEY="your-key" olostep/mcp-server

许可证

ISC 许可证