> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Olostep MCP 服务器

> 在不到一分钟内为任何兼容 MCP 的 AI 客户端提供网页抓取、搜索、爬虫和 AI 答案工具

Olostep MCP 服务器为任何兼容 MCP 的 AI 客户端（Claude、Cursor、Windsurf、VS Code、Claude Code 等）提供 10 个即用型工具，用于实时网络——抓取、搜索、带引用的 AI 答案、批处理作业、网站爬虫和 URL 发现。

<CardGroup cols={2}>
  <Card title="抓取和提取" icon="file-lines">
    从任何 URL 提取 markdown、HTML、JSON 或文本，支持可选的 JS 渲染
  </Card>

  <Card title="AI 答案" icon="sparkles">
    基于网络的答案，附带来源和结构化输出
  </Card>

  <Card title="批处理和爬虫" icon="layer-group">
    最多支持 10k 个 URL 并行处理，或自主发现整个网站
  </Card>

  <Card title="地图和搜索" icon="map">
    查找网站上的每个 URL，或运行基于解析器的网络搜索
  </Card>
</CardGroup>

## 开始之前

你需要一个 Olostep API 密钥。可以从 [Olostep 仪表板](https://www.olostep.com/dashboard/api-keys) 获取一个——免费层覆盖个人使用。

## 选择安装路径

对于每个客户端，最快的路径是使用托管端点 `https://mcp.olostep.com/mcp`。无需安装，无需 Node，无需 Docker——只需粘贴一个 URL 和你的 API 密钥。

如果你需要完全本地运行（离线使用、公司代理、隔离网络），每个客户端也支持通过 `npx` 的本地 stdio 安装。下面的每个部分都展示了这两种方式。

<Note>
  **托管端点**使用 `Authorization: Bearer YOUR_API_KEY`。**本地 stdio**使用 `OLOSTEP_API_KEY` 作为环境变量。不要混淆它们——错误的认证模式是最常见的入门错误。
</Note>

## 客户端设置

<Tabs>
  <Tab title="Cursor">
    **一键安装（推荐）：**

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=olostep&config=eyJ1cmwiOiJodHRwczovL21jcC5vbG9zdGVwLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19">
      <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="将 Olostep MCP 服务器添加到 Cursor" style={{ maxHeight: 32 }} />
    </a>

    在生成的配置中将 `YOUR_API_KEY` 替换为你的真实密钥。

    **手动设置：**

    在项目根目录创建或编辑 `.cursor/mcp.json`（或全局的 `~/.cursor/mcp.json`）：

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="本地 stdio 安装（可选）">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      需要在你的机器上安装 Node.js 18+。
    </Accordion>

    **验证：** 打开 Cursor → 设置 → MCP。你应该看到 `olostep` 列出 **10 个工具**，包括 `scrape_website`。如果看到“已连接，0 个工具”，说明你的 API 密钥错误。
  </Tab>

  <Tab title="Claude Code">
    **CLI 安装（推荐）：**

    ```bash theme={null}
    claude mcp add --transport http olostep https://mcp.olostep.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    **手动设置：**

    添加到你的 Claude Code MCP 配置（项目根目录的 `.mcp.json`，或全局的 `~/.claude.json`）：

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="本地 stdio 安装（可选）">
      ```bash theme={null}
      claude mcp add --transport stdio --env OLOSTEP_API_KEY=YOUR_API_KEY olostep \
        -- npx -y olostep-mcp
      ```

      或作为 JSON：

      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **验证：** 在 Claude Code 中运行 `/mcp`。你应该看到 `olostep` 已连接，并有 10 个工具。
  </Tab>

  <Tab title="Claude Desktop">
    **配置文件位置：**

    | 操作系统    | 路径                                                                |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    **托管（推荐）：**

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="本地 stdio 安装（可选）">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      或通过 Smithery 安装：

      ```bash theme={null}
      npx -y @smithery/cli install @olostep/olostep-mcp-server --client claude
      ```
    </Accordion>

    <Warning>
      必须完全退出并重新启动 Claude Desktop 才能使配置更改生效——仅关闭窗口是不够的（它会在菜单栏/系统托盘中继续运行）。
    </Warning>

    **验证：** 打开 Claude Desktop → 在聊天输入中寻找 🔨（锤子）图标。点击它——你应该看到列出的 10 个 Olostep 工具。
  </Tab>

  <Tab title="VS Code">
    VS Code 的 MCP 支持内置于 GitHub Copilot（代理模式）中。在你的项目中添加到 `.vscode/mcp.json`，或在你的用户 `settings.json` 中：

    ```json theme={null}
    {
      "servers": {
        "olostep": {
          "type": "http",
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="本地 stdio 安装（可选）">
      ```json theme={null}
      {
        "servers": {
          "olostep": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **验证：** 打开 Copilot 聊天面板 → 切换到代理模式 → 工具弹出窗口应该列出 Olostep 工具。
  </Tab>

  <Tab title="Windsurf">
    添加到 `~/.codeium/windsurf/mcp_config.json`：

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "serverUrl": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="本地 stdio 安装（可选）">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **验证：** 级联 → 设置 → MCP。`olostep` 应该出现，并有 10 个工具。
  </Tab>

  <Tab title="Docker">
    如果你更愿意在容器中运行服务器（CI、隔离环境、主机上无 Node）：

    ```bash theme={null}
    docker pull olostep/mcp-server

    docker run -i --rm \
      -e OLOSTEP_API_KEY="YOUR_API_KEY" \
      olostep/mcp-server
    ```

    在 MCP 客户端配置中（stdio）：

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-e", "OLOSTEP_API_KEY=YOUR_API_KEY",
            "olostep/mcp-server"
          ]
        }
      }
    }
    ```

    支持 `linux/amd64` 和 `linux/arm64`。源码在 [GitHub](https://github.com/olostep/olostep-mcp-server)。
  </Tab>

  <Tab title="Metorial">
    1. 打开 [Metorial 仪表板](https://metorial.com)
    2. 导航到 **MCP 服务器**
    3. 搜索 **Olostep**
    4. 点击 **安装** 并粘贴你的 API 密钥

    手动配置：

    ```json theme={null}
    {
      "olostep": {
        "command": "npx",
        "args": ["-y", "olostep-mcp"],
        "env": {
          "OLOSTEP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 选择合适的工具

MCP 服务器提供 10 个工具。使用此决策树选择合适的工具——代理使用相同的推理：

| 你的需求是...     | 使用                                        | 备注                                         |
| ------------ | ----------------------------------------- | ------------------------------------------ |
| 某个特定页面的内容    | `scrape_website` 或 `get_webpage_content`  | 对于 SPA 设置 `wait_before_scraping=2000–5000` |
| 带来源的自然语言网络答案 | `answers`                                 | 返回 AI 综合 + 引用                              |
| 查询的搜索结果      | `search_web`                              | 基于解析器，非 AI，结构化                             |
| 网站上的 URL 列表  | `create_map`                              | 仅 URL 发现——不抓取                              |
| 按查询过滤的 URL   | `get_website_urls`                        | 按与你的 `search_query` 的相关性排序                 |
| 一次处理多个已知 URL | `batch_scrape_urls` + `get_batch_results` | 异步——启动后轮询                                  |
| 整个网站或部分      | `create_crawl` + `get_crawl_results`      | 异步——从起始 URL 跟随链接                           |

<Tip>
  **抓取整个网站？** 使用 `create_crawl`，而不是 `batch_scrape_urls`。爬虫发现并抓取。批处理适用于你已有的已知 URL 列表。
</Tip>

### 工具详情

<Accordion title="scrape_website">
  从单个 URL 提取内容。支持 `markdown`、`html`、`json`、`text`。可选 `country` 用于地理定位请求，`wait_before_scraping`（0–10000 毫秒）用于 JS 密集型网站，以及 `parser`（例如 `@olostep/amazon-product`）用于结构化提取。
</Accordion>

<Accordion title="get_webpage_content">
  `scrape_website` 的轻量级 markdown 版本。仅用于当你只想要干净的 markdown 而不需要格式选项时。
</Accordion>

<Accordion title="search_web">
  查询的结构化（基于解析器）网络搜索结果。可选 `country` 用于本地化结果。返回 JSON，而不是 AI 文本。
</Accordion>

<Accordion title="answers">
  AI 驱动的 `task` 答案，附带来源和引用。传递一个 `json` 参数以特定格式获取答案——可以是 JSON 架构或简短的自然语言描述。
</Accordion>

<Accordion title="batch_scrape_urls">
  异步抓取你已有的 2–10k 个 URL。返回一个 `batch_id`——然后调用 `get_batch_results` 获取内容。设置 `wait_for_completion_seconds`（最多 900）如果你想要一个单一的阻塞调用而不是轮询。推荐：对于少于 50 个 URL 的批次为 60，50–1k 为 300–600，0（单独轮询）用于更大的批次。
</Accordion>

<Accordion title="get_batch_results">
  获取 `batch_id` 的状态和抓取内容。返回 `processing` 直到完成，然后返回 `completed` 和项目数组。
</Accordion>

<Accordion title="create_crawl">
  从 `start_url` 开始的异步爬虫。使用 `include_url_patterns` / `exclude_url_patterns`（如 `/blog/**` 的 glob 语法）进行范围限定。返回一个 `crawl_id`——然后调用 `get_crawl_results`。
</Accordion>

<Accordion title="get_crawl_results">
  获取 `crawl_id` 的状态和页面。通过 `cursor` 和 `items_limit`（每次调用最多 100 个）支持分页。返回 `in_progress` 直到完成。
</Accordion>

<Accordion title="create_map">
  获取网站上的 URL 列表。仅 URL 发现——不抓取。用于当你想要展示候选 URL（例如让用户选择一个子集）时。支持 `include_url_patterns` / `exclude_url_patterns` 和 `search_query`。
</Accordion>

<Accordion title="get_website_urls">
  类似于 `create_map`，但 URL 按与必需的 `search_query` 的相关性排序。用于当你想要网站上前 N 个匹配链接时。
</Accordion>

## 故障排除

<Accordion title="服务器出现但显示 0 个工具">
  你的 API 密钥无效或受限。打开 [API 密钥仪表板](https://www.olostep.com/dashboard/api-keys) 并验证密钥。如果使用托管端点，标题必须是 **完全** `Authorization: Bearer sk_...`——值周围没有引号，没有多余的空格。
</Accordion>

<Accordion title="`npx: command not found` 或 `command not found: olostep-mcp`">
  Node.js 未安装（或不在你的 PATH 中）。从 [nodejs.org](https://nodejs.org/) 安装 Node 18+，然后重启你的终端 **和** 你的 MCP 客户端。在 Windows 上，切换到具有 Node 在 PATH 上的 CMD/PowerShell。
</Accordion>

<Accordion title="`mcp.olostep.com` 上的连接被拒绝或 DNS 错误">
  你可能在公司代理或防火墙后面阻止了主机。切换到本地 stdio 安装（`npx -y olostep-mcp`）——它改为向 `api.olostep.com` 发出出站请求，这通常是允许的。
</Accordion>

<Accordion title="编辑配置但工具列表未更新">
  客户端缓存了旧配置。完全退出并重新启动——不仅仅是关闭窗口。Claude Desktop 特别是在菜单栏/系统托盘中继续运行。
</Accordion>

<Accordion title="Windows 特有的 `npx` 失败">
  如果 `npx` 在 Windows 上启动服务器时出错，请使用 CMD 包装形式：

  ```json theme={null}
  {
    "command": "cmd",
    "args": ["/c", "npx", "-y", "olostep-mcp"],
    "env": { "OLOSTEP_API_KEY": "YOUR_API_KEY" }
  }
  ```
</Accordion>

<Accordion title="`401 Missing Authorization: Bearer <OLOSTEP_API_KEY>`">
  你在没有认证头的情况下访问托管端点（或格式错误）。按照设置选项卡中显示的方式将头添加到你的客户端配置中。
</Accordion>

## 配方

复制粘贴与工具配合良好的提示：

* **抓取产品 URL 列表：** *"我有一个包含 200 个亚马逊产品 URL 的 CSV。使用 `parser=@olostep/amazon-product` 批量抓取它们并返回 JSON。"*
* **爬取文档网站：** *"爬取 [https://stripe.com/docs，\`max\_pages=50\`](https://stripe.com/docs，`max_pages=50`) 和 `include_url_patterns=['/docs/**']`。将每个部分总结为 markdown。"*
* **寻找竞争对手：** *"使用 `answers` 找到 Notion 的技术文档网站的前 5 个竞争对手。返回名称、主页和一句话定位。"*
* **先映射后抓取：** *"在 [https://example.com](https://example.com) 上运行 `create_map`，过滤到 `/blog/**`，然后在前 20 个结果上运行 `batch_scrape_urls`。"*

## 源码及版本

* [GitHub 仓库](https://github.com/olostep/olostep-mcp-server)
* [npm 包](https://www.npmjs.com/package/olostep-mcp)
* [Docker Hub](https://hub.docker.com/r/olostep/mcp-server)
* [MCP 注册表](https://registry.modelcontextprotocol.io/)