Claude Code 中的 SEO 工具：托管与本地 MCP 对比 — Agent Lab Journal

  Agent Lab Journal

    Guides
    Glossary

Enter fullscreen mode Exit fullscreen mode

Practical guide · Intermediate

Claude Code 中的 SEO 工具：托管与本地 MCP 对比 

      45-minute read
      Updated July 30, 2026
      Intermediate

Enter fullscreen mode Exit fullscreen mode

如果编码代理无法检索当前的搜索环境，就无法对其进行分析。本指南通过模型上下文协议（MCP）将 Claude Code 连接到实时 SERP 数据，然后使用相同的查询、位置、语言、设备和输出契约，比较托管 HTTP 服务器与本地 stdio 服务器。

本指南内容

  • 问题与目标结果

  • 托管 HTTP 与本地 stdio

  • 受控 SEO 案例

  • 前置条件与安全

  • 连接托管 MCP 服务器

  • 连接本地 stdio 服务器

  • 运行对比

  • 验证证据

  • 失败案例

  • 局限性与选择指南

问题与目标结果

Claude Code 可以检查代码仓库、编辑文件、运行命令，并对提供的上下文进行推理。但这并不自动赋予它访问当前搜索引擎优化（SEO）数据集的权限。如果没有搜索数据工具，该代理可能知道如何分析排名，但无法确定特定市场当前的排名。

通常的解决方法是手动操作：在浏览器或第三方平台中运行搜索、导出结果、将其粘贴到会话中，并在查询更改时重复此过程。这既缓慢又会引入多种错误来源：

  • 复制的结果可能遗漏排名、结果类型、URL 或查询参数；

  • 搜索可能使用未受控的位置、语言、设备或登录状态；

  • 代理无法在验证自身结论的同时重复检索；

  • 两次测试运行可能无声地使用不同设置；

  • 大量粘贴的响应会消耗上下文，且没有稳定的数据契约。

目标结果更窄且更可靠：Claude Code 应发现一个 MCP 搜索工具，使用显式参数调用它，接收结构化结果，并保存足够的元数据以便他人重复调用。您将配置两种传输方式，并在不假设其中任何一种普遍更好的情况下进行比较。

预期结果

完成后，您将拥有一个已连接的托管 HTTP MCP 服务器、一个已连接的本地 stdio MCP 服务器，以及针对单个受控 SERP 请求的比较记录。该记录将包含观察到的输出，而不是虚构的基准数字。

托管 HTTP 与本地 stdio

托管 MCP 服务器在您的机器外部运行，并通过 HTTPS 访问。Claude Code 连接到远程端点，而提供商则负责服务器进程的运行，通常还处理扩展和更新。

本地 stdio 传输在您的机器上启动程序，并通过标准输入和标准输出交换协议消息。该程序可以从远程搜索数据服务检索 SERP 数据、查询本地索引，或封装另一个命令行工具。“本地 MCP”描述的是 MCP 进程的运行位置；它并不证明底层搜索数据是本地的。

            Dimension
            Hosted HTTP
            Local stdio




            Server operation
            Handled by the remote operator
            Handled on the developer machine


            Connection
            Remote HTTPS endpoint
            Child process over stdin and stdout


            Initial setup
            Usually endpoint plus authentication
            Runtime, package, command, and environment


            Updates
            May change remotely
            Can be pinned to a known version


            Debugging
            Depends on remote logs and error detail
            Local stderr and process inspection are available


            Secret exposure
            Credentials and requests reach a remote service
            Local wrapper secrets remain local, but its upstream calls may not


            Team consistency
            One endpoint can simplify shared access
            Requires reproducible local installation

Enter fullscreen mode Exit fullscreen mode

传输只是系统的一部分。公平的比较必须将 MCP 连接行为与上游搜索数据源分开。如果托管服务器和本地服务器使用不同的 SERP 提供商，排名差异可能来自提供商的收集方法，而非 HTTP 与 stdio 的差异。

受控 SEO 案例

假设一个小型编辑仓库包含一篇关于选择可观测性堆栈的草稿。编辑希望了解“open source observability tools”查询的结果类型和竞争页面，以便修改草稿。

这是一个可重复的演示查询，并非对任何公司、客户或排名结果的声明。您可以用与您的网站相关的查询替换它。未经授权，请勿将机密产品计划或未发布的客户条款混入第三方搜索 API。

测试前冻结请求

创建测试规范，并在两种传输方式中使用不变的规范：

{
  "query": "open source observability tools",
  "country": "us",
  "language": "en",
  "device": "desktop",
  "limit": 10,
  "safe_search": true
}

Enter fullscreen mode Exit fullscreen mode

确切的字段名称取决于您的 MCP 服务器。映射一次，然后记录实际发送的最终参数。如果服务器支持位置标识符而非国家代码，请选择一个位置，并在两次调用中使用其等效值。

定义最小结果契约

要求每个服务器在提供商公开的地方返回：

  • 规范化后的查询；

  • 国家或位置、语言和设备；

  • 检索时间或提供商时间戳；

  • 自然排名、标题、URL 和可见描述；

  • 结果类型，例如自然结果、视频、新闻或精选区块；

  • 提供商警告、截断标志和请求标识符；

  • 工具名称和工具模式版本（如果可用）。

不要强迫代理推断缺失的元数据。仅包含 URL 的列表，而没有区域设置和检索时间，不足以作为当前排名分析的证据。

前置条件与安全

您需要 Claude Code、终端，以及访问暴露合法搜索或 SERP 检索工具的 MCP 服务器的权限。对于本地包，您还需要其支持的运行时。以下示例使用占位符，因为服务器名称、工具模式、身份验证方法和 Claude Code 命令选项可能因版本和提供商而异。

收集这些值

  • HOSTED_MCP_URL：已记录的 HTTPS 端点；

  • HOSTED_MCP_TOKEN：如果端点需要令牌，则为作用域令牌；

  • LOCAL_MCP_COMMAND：已记录的可执行文件或包运行程序；

  • SERP_API_KEY：如果本地服务器需要上游凭据；

  • 两个服务器的确切搜索工具名称和输入模式。

API 密钥不得提交到仓库、粘贴到文章中、不必要地放入 shell 历史记录中，或写入团队将提交的项目范围 MCP 文件中。优先使用环境变量引用、操作系统密钥存储，或服务器记录的身份验证机制。

连接服务器前

审查服务器可以读取的内容以及它暴露的工具。使用范围狭窄的凭据，尽可能在搜索提供商处设置支出限制，并确认查询或仓库上下文是否被保留。MCP 连接本身并不是安全边界。

检查 Claude Code 当前的命令语法

从已安装的客户端开始，而不是盲目复制特定于版本的命令：

claude --version
claude mcp --help
claude mcp add --help
claude mcp list

Enter fullscreen mode Exit fullscreen mode

使用已安装版本显示的形式。下一节中的示例说明了配置意图，并使用了占位符名称；它们并不断言每个版本都接受相同的标志。

连接托管 HTTP MCP 服务器

Streamable HTTP 传输允许 MCP 客户端通过 HTTP 端点与远程服务器通信。使用服务器操作符记录的 URL 和身份验证标头。不要猜测端点路径。

1. 将令牌放入环境 

export HOSTED_MCP_TOKEN='replace-with-your-scoped-token'

Enter fullscreen mode Exit fullscreen mode

此导出仅在当前 shell 会话中有效。对于常规使用，请通过批准的密钥管理工作流加载该值，而不是将字面令牌存储在仓库文件中。

2. 添加服务器

如果已安装的 Claude Code 版本支持 HTTP 类型和标头扩展，命令可能遵循以下模式：

claude mcp add \
  --transport http \
  --header "Authorization: Bearer ${HOSTED_MCP_TOKEN}" \
  seo-hosted \
  "https://YOUR-MCP-HOST.example/mcp"

Enter fullscreen mode Exit fullscreen mode

用 claude mcp add --help 和服务器文档中的值替换 URL 和标志。如果客户端将配置存储在 JSON 中，请使用等效的远程服务器条目，同时将密钥排除在已提交的文本之外。

3. 确认注册和连接 

claude mcp list
claude mcp get seo-hosted

Enter fullscreen mode Exit fullscreen mode

检查显示的传输方式是否为 HTTP，主机名是否正确，以及密钥是否已脱敏。然后打开 Claude Code，并使用客户端的 MCP 接口检查 MCP 服务器状态。仅仅因为存在配置条目并不意味着连接已验证。

4. 在请求分析前检查工具

确认服务器暴露了搜索工具并阅读其模式。诸如 search_serp 之类的合理名称并不能证明这就是真实的工具名称。注意必填字段、允许的国家和设备值、最大结果数，以及是否包含检索时间。

5. 运行窄范围冒烟测试

在 Claude Code 中，使用需要工具调用但尚未要求战略结论的提示：

Use only the MCP server named seo-hosted.

Find its tool for retrieving a current search results page. Show me:
1. the exact tool name,
2. the input arguments you will send,
3. the retrieval result for this fixed request:
   query: open source observability tools
   country: US
   language: English
   device: desktop
   limit: 10

Do not estimate rankings from memory. If a parameter is unsupported,
stop and identify it. Preserve the returned order and include the
retrieval timestamp or explicitly state that the provider omitted it.

Enter fullscreen mode Exit fullscreen mode

将工具调用参数和原始结构化响应保存在对话摘要之外。不要手动编辑排名。

连接本地 stdio MCP 服务器

本地变体应暴露等效的搜索功能。理想情况下，两个服务器应使用相同的上游数据提供商和兼容的参数。否则，请将该实验标记为端到端实现比较，而不是纯粹的传输基准。

1. 固定并检查包

使用服务器的官方安装说明。避免在可重复的基准测试中使用未固定的“latest”依赖项。在运行第三方包之前，请检查其源代码、包所有权、请求的权限和发布信息。

通用的包运行程序模式如下所示：

npx --yes @YOUR-SCOPE/seo-mcp-server@PINNED_VERSION --help

Enter fullscreen mode Exit fullscreen mode

对于基于 Python 的服务器，记录的命令可能改为使用隔离的运行程序或虚拟环境。关键要求是特定的已审查包版本，而不是特定的生态系统。

2. 提供上游凭据 

export SERP_API_KEY='replace-with-your-scoped-key'

Enter fullscreen mode Exit fullscreen mode

如果服务器支持模拟、缓存或本地索引模式，请决定该模式是否满足目标。缓存结果可以测试 MCP 集成，但不能证明访问当前 SERP。

3. 添加 stdio 进程

根据已安装的 CLI 语法，stdio 注册可能类似于：

claude mcp add \
  --transport stdio \
  --env SERP_API_KEY="${SERP_API_KEY}" \
  seo-local \
  -- npx --yes @YOUR-SCOPE/seo-mcp-server@PINNED_VERSION

Enter fullscreen mode Exit fullscreen mode

某些版本会以不同的方式将 Claude Code 选项与子命令分开。请通过本地帮助输出确认分隔符、环境语法和配置范围。

4. 保持协议输出干净

stdio MCP 进程必须保留 stdout 用于协议消息。调试横幅和普通日志应输出到 stderr。将安装通知或彩色日志打印到 stdout 的包可能会破坏通信，即使其底层搜索请求成功。

5. 确认本地进程和工具 

claude mcp list
claude mcp get seo-local

Enter fullscreen mode Exit fullscreen mode

从包含所需运行时和凭据的环境中启动 Claude Code。检查服务器状态，并将本地工具模式与托管模式进行比较。在运行共享测试前记录任何不匹配。

6. 运行等效冒烟测试 

Use only the MCP server named seo-local.

Find its tool for retrieving a current search results page. Show me:
1. the exact tool name,
2. the input arguments you will send,
3. the retrieval result for this fixed request:
   query: open source observability tools
   country: US
   language: English
   device: desktop
   limit: 10

Do not estimate rankings from memory. If a parameter is unsupported,
stop and identify it. Preserve the returned order and include the
retrieval timestamp or explicitly state that the provider omitted it.

Enter fullscreen mode Exit fullscreen mode

运行公平的托管与本地对比

MCP 比较中的核心错误是向每个服务器提出广泛的问题并比较散文答案。这衡量的是代理措辞、提示变化，以及可能不同的工具选择。首先比较工具调用和原始记录；其次再进行分析。

测试协议

  • 使用相同的 Claude Code 版本和模型配置。

  • 从新会话开始两次运行，以避免一个结果污染另一个。

  • 使用固定的查询、区域设置、语言、设备、结果限制和安全设置。

  • 尽可能在相近的时间运行调用，并记录实际时间戳。

  • 要求每个会话仅使用其命名的 MCP 服务器。

  • 捕获确切的工具名称、参数、结构化响应、错误和警告。

  • 不要无声地重试。记录每次尝试和重试原因。

  • 仅规范化呈现差异；分别保留原始记录。

使用单一输出模式

要求 Claude Code 编写或显示如下规范化记录。保留缺失值为 null；不要用猜测填充它们：

{
  "transport": "hosted-http-or-local-stdio",
  "server_name": "configured-server-name",
  "tool_name": "actual-tool-name",
  "started_at": "observed-ISO-8601-time",
  "completed_at": "observed-ISO-8601-time",
  "request": {
    "query": "open source observability tools",
    "country": "us",
    "language": "en",
    "device": "desktop",
    "limit": 10
  },
  "provider_metadata": {
    "retrieved_at": null,
    "request_id": null,
    "cache_status": null
  },
  "results": [
    {
      "rank": 1,
      "type": "organic",
      "title": "value-returned-by-provider",
      "url": "value-returned-by-provider",
      "displayed_url": null,
      "description": null
    }
  ],
  "warnings": [],
  "error": null
}

Enter fullscreen mode Exit fullscreen mode

记录观察结果，而非预期的赢家

在测试前使用空白工作表，仅根据观察到的行为填充：

            Measure
            Hosted HTTP
            Local stdio
            How to verify




            Connected successfully
            Not tested
            Not tested
            Client status and successful tool discovery


            Tool name
            Record actual value
            Record actual value
            Tool inventory


            Parameters supported
            Record actual fields
            Record actual fields
            Published tool schema


            Result count
            Record actual count
            Record actual count
            Count structured records


            Metadata completeness
            Record missing fields
            Record missing fields
            Inspect raw response


            Elapsed time
            Measure locally
            Measure locally
            Completion minus start time


            Retries
            Record attempts
            Record attempts
            Session and server logs


            Top-10 URL overlap
            Calculate after both successful calls
            Compare normalized URLs

Enter fullscreen mode Exit fullscreen mode

计算重叠率，而不假装它证明准确性

保守地规范化 URL：将主机名小写，移除片段，并仅移除您可以安全识别的跟踪参数。不要折叠不同的路径或基于假设规范化 URL。

对于两组返回的 URL，计算：

overlap_count = number of normalized URLs present in both result sets
union_count   = number of unique normalized URLs across both sets
jaccard       = overlap_count / union_count

Enter fullscreen mode Exit fullscreen mode

高重叠率表明观察到的数据集之间存在一致性。它并不能证明任一数据集都与匿名用户在浏览器中看到的内容完全匹配。低重叠率可能表明时间、区域设置、个性化、缓存、参数映射、提供商差异或解析行为。

单独测量排名变动

对于同时出现在两个响应中的 URL，记录其排名差异：

rank_delta = local_stdio_rank - hosted_http_rank

Enter fullscreen mode Exit fullscreen mode

在报告中保留符号约定。不要在忽略仅出现在一个响应中的 URL 的情况下平均排名差；分别报告共享 URL 和独占 URL。

验证代理使用了实时工具数据

流畅的回答不是验证。需要从连接到工具调用再到结构化输出的可追溯路径。

连接检查

  • 两个配置的名称都出现在 MCP 服务器列表中。

  • 托管条目指向预期的 HTTPS 主机名。

  • 本地条目启动预期的固定命令。

  • 密钥未在状态输出或保存的工件中打印。

  • 每个服务器在 Claude Code 会话中报告可用状态。

工具检查

  • 代理命名实际发现的工具，而不是虚构一个。

  • 参数与固定的测试规范匹配。

  • 不支持的参数被报告，而不是被无声地丢弃。

  • 结果顺序被保留。

  • 原始响应包含代理总结的 URL。

新鲜度检查

  • 优先使用提供商检索时间戳，而不是代理的会话时间。

  • 在暴露时记录缓存状态和缓存年龄。

  • 如果不存在新鲜度元数据，则将新鲜度标记为未验证。

  • 不要仅仅因为网络调用成功就将结果描述为“实时”。

请求来源报告 

For the SERP data you just returned, provide a provenance report.

Include:
- MCP server name;
- exact tool name;
- exact tool arguments;
- provider retrieval timestamp, if returned;
- cache status, if returned;
- fields omitted by the provider;
- any transformation you performed;
- any claim in your summary that was not directly supported by tool output.

Do not call another tool and do not reconstruct missing metadata.

Enter fullscreen mode Exit fullscreen mode

可选的浏览器抽查

手动搜索可以识别明显的异常，但除非环境受控，否则它不能替代真实情况。搜索引擎可能会因精确位置、时间、数据中心、同意状态、个性化和页面布局而产生不同的结果。记录浏览器的设置和时间戳，并将此练习称为抽查，而不是决定性的准确性测试。

通过条件

当 Claude Code 能够发现预期的工具、发送固定的请求、接收结构化的搜索记录、诚实地暴露缺失的元数据，并保留足够的来源以重复调用时，集成即通过。托管与本地输出之间的一致性是单独的测量。

失败案例与诊断

托管服务器未授权

症状：HTTP 401 或 403 响应、工具发现失败，或重复的身份验证提示。

检查：验证令牌是否存在于启动 Claude Code 的环境中，确认预期的标头名称和令牌前缀，检查令牌范围和到期时间，并确保端点属于预期的环境。调试时切勿打印完整令牌。

端点已连接但未暴露搜索工具

症状：服务器状态健康，但所需的 SERP 工具缺失。

检查：确认您使用了正确的 MCP 端点、账户计划、工作区和服务器版本。检查已发现的工具列表。健康的 MCP 服务器可能不是正确的服务器。

本地服务器立即退出

症状：断开连接状态、未找到进程错误，或初始化期间失败。

检查：使用 --help 运行记录的命令，确认 Claude Code 的环境中存在运行时，检查固定的包版本，并检查 stderr。在交互式 shell 中工作的命令在 PATH 或环境初始化不同时可能会失败。

stdio 上的协议解析失败

症状：格式错误的消息、意外字符或初始化超时。

检查：查找写入 stdout 的横幅、调试日志、进度条或包管理器通知。将日志配置为输出到 stderr，禁用装饰性输出，并避免向协议流注入文本的包装器。

工具拒绝区域设置或设备值

症状：验证错误或参数被无声更改。

检查：检查工具的输入模式。一台服务器可能接受 us，另一台接受 United States，另一台接受数字位置 ID。记录映射。如果无法建立等效定位，请不要将输出比较称为受控。

响应为空

症状：成功的工具调用但没有结果。

检查：检查警告、配额状态、安全设置、查询编码、区域设置支持和提供商响应字段。不要让代理用记住或推断的排名替换空响应。

响应太大，无法进行有效分析

症状：上下文压力、工具输出被截断，或缺少排名较低的记录。

检查：仅请求所需的结果数量和字段。将检索与页面内容提取分开。对于初始测试，十条结果记录通常比十个页面的完整 HTML 更有用。

托管与本地输出不同

症状：不同的 URL、排名顺序、结果类型或元数据。

检查：比较请求时间戳、提供商身份、位置映射、语言、设备、缓存状态、安全搜索设置、规范化规则、分页和解析器版本。在这些变量得到控制之前，不要将差异归因于传输方式。

代理在未调用任何工具的情况下回答

症状：无工具跟踪、通用竞争对手、缺少时间戳，或在没有记录的情况下声称“当前排名”。

检查：将提示限制为一个命名的服务器，要求提供确切参数和来源，并声明如果工具不可用，任务必须停止。将无跟踪的响应视为失败的运行。

速率限制或成本扭曲测试

症状：节流、长时间退避、部分结果或意外消耗。

检查：测试前检查配额，限制结果，避免不受控制的重试，并记录提供商错误代码。更便宜的传输并不意味着更便宜的搜索数据；上游请求可能主导成本。

局限性与选择指南

本比较可以确立的内容

  • 每个 MCP 连接是否在您的 Claude Code 环境中正常工作；

  • 是否支持所需的查询参数；

  • 输出是否足够结构化和可追溯；

  • 测试中观察到的延迟、错误、元数据和结果一致性；

  • 每种配置所需的运营工作。

单个查询无法确立的内容

  • 跨市场、语言、设备和结果类型的通用准确性；

  • 长期可靠性或提供商正常运行时间；

  • 并发下的典型性能；

  • 完整的隐私、安全或合规性特征；

  • HTTP 或 stdio 导致搜索结果的差异；

  • 提供商的数据集与每个用户可见的搜索页面匹配。

选择托管 HTTP 的情况

  • 团队需要集中操作的端点；

  • 开发人员不应安装和维护本地运行时；

  • 远程身份验证和访问控制符合组织的政策；

  • 提供商提供您需要的可观测性、保留政策和数据处理；

  • 一致的部署比本地进程控制更重要。

选择本地 stdio 的情况

  • 您需要检查或修改 MCP 包装器；

  • 您希望将服务器实现固定到已审查的版本；

  • 本地 stderr 和进程级调试有价值；

  • 团队可以复制运行时和包安装；

  • 凭据必须通过本地密钥工作流注入。

这两种选择都不能消除评估上游 SERP 来源的必要性。本地包装器围绕远程 API 仍会向该 API 发送查询。托管服务器也可能是围绕同一提供商的薄包装器。记录两个层：MCP 传输和搜索数据来源。

可重复的操作工作流

一旦比较通过，就将其转化为小型的、受控的研究程序，而不是开放式的“做 SEO”提示。

阶段 1：检索 

Use seo-hosted to retrieve exactly 10 results for the fixed request.
Return structured records and provenance only. Do not recommend changes yet.

Enter fullscreen mode Exit fullscreen mode

阶段 2：验证 

Check the returned records for missing rank, URL, result type, locale,
device, retrieval time, cache status, warnings, and truncation.
Mark each missing field as unknown. Do not infer it.

Enter fullscreen mode Exit fullscreen mode

阶段 3：分析 

Using only the validated records, identify:
- recurring page formats;
- dominant search intent;
- result features visible in the dataset;
- title patterns;
- domains appearing more than once.

Separate direct observations from hypotheses. Do not claim traffic,
search volume, authority, or content quality unless the tool returned
evidence for those claims.

Enter fullscreen mode Exit fullscreen mode

阶段 4：应用于仓库 

Compare the validated SERP observations with the current draft.
Propose changes that are supported by the evidence.
Do not rewrite files until you show:
1. the evidence,
2. the proposed change,
3. the expected editorial effect.

Enter fullscreen mode Exit fullscreen mode

阶段 5：保留审计记录

存储查询规范、时间戳、服务器名称、工具名称、规范化记录、原始响应位置、警告和分析提示。排除凭据和敏感标头。如果仓库不应包含研究数据，请将记录存储在批准的外部位置，并仅引用其标识符。

最终检查清单

  • 托管服务器使用记录的 HTTPS 端点。

  • 本地服务器命令已审查并固定版本。

  • 密钥的作用域已限定，且未出现在已提交的文件中。

  • 两个服务器都暴露了适当的搜索工具。

  • 固定的请求使用相同的查询、区域设置、语言、设备和限制。

  • 两次运行都记录实际时间戳和每次重试。

  • 在规范化之前保留原始响应。

  • 缺失的元数据保持未知，而不是被推断。

  • URL 重叠率和排名差异根据观察到的记录计算。

  • 提供商差异未被错误地归因于 MCP 传输。

  • 最终的 SEO 分析区分证据和假设。

实际的成功标准很简单：编码代理不再需要人员将搜索结果粘贴到每个会话中，但每个排名声明都与显式的工具调用和可重复的请求相关联。托管 HTTP 减少了本地运营工作；本地 stdio 提供了对包装器和运行时的更大控制。您记录的测试——而不是假设的基准——应该决定哪种权衡适合项目。

继续阅读 Agent Lab Journal 指南，或在本术语表中查看此处使用的术语。

© 2026 Agent Lab Journal

Original article: https://agentlabjournal.online/en/seo-mcp-for-claude-code-hosted-vs-local.html?utm_source=devto&utm_medium=referral&utm_campaign=agentlabjournal-en-global-all&utm_content=article&utm_term=seo-mcp-for-claude-code-hosted-vs-local