为 Claude、Cursor 与 Codex 接入 OpenSEO MCPOAuth 与 API Key 双认证配置全指南【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seoOpenSEO 将关键词研究、SERP 检查、本地商家调研、竞品情报、域名分析、外链概览、已保存关键词、排名追踪、项目共享上下文以及 Google Search Console 表现与 URL 检查等能力通过 MCPModel Context Protocol暴露给兼容的 AI 客户端。本文基于官方文档 web/content/docs/mcp.md 完整梳理托管 MCP 服务器的连接方式并结合仓库源码transport.ts、oauth-provider.ts、api-key-auth.ts、server.ts 等讲解其背后的 OAuth 授权、API Key 认证与工具注册机制。读完本文你将掌握在 Claude Code、Claude Desktop、Cursor、Codex CLI、Codex Desktop 中接入 OpenSEO MCP 的全部步骤、无头环境下的 API Key 连接方式以及常见故障的排查思路。OpenSEO MCP 是什么OpenSEO MCP 是一套部署在 Cloudflare Workers 上的 MCP 服务器实现让兼容的 AI 客户端可以直接调用 OpenSEO 的 SEO 研究工具覆盖关键词研究、SERP 检查、本地商家研究、竞争搜索情报、域名研究、外链概览、已保存关键词、排名追踪、共享项目上下文以及 Google Search Console 表现与 URL 检查等能力。托管 MCP 服务器地址为https://app.openseo.so/mcp首次连接会引导你完成 OpenSEO 登录。授权通过后你的 MCP 客户端即可使用你批准的项目上下文与账户范围来调用 OpenSEO 工具。对于无头环境和 CI请改用 API Key 连接见下文对应小节。提示最新版设置界面与可复制端点可打开 OpenSEO 应用中的AI MCP页面查看。服务端实现工具、指令与授权上下文在深入客户端配置前先看服务端是如何组织这些能力的这有助于理解后续每个连接选项的意义。MCP 服务器与工具注册服务端入口是 src/server/mcp/server.ts 中的createOpenSeoMcpServer它基于modelcontextprotocol/server构建服务器元信息声明了名称 OpenSEO MCP、版本以及一句高度浓缩的能力描述。所有工具通过registerOpenSeoTool统一注册每个工具声明inputSchemaZod 结构与可选的outputSchema并经由instrumentMcpToolHandler包裹以接入遥测instrumentation.ts。服务器还携带两条对 Agent 行为有直接影响的元信息capabilities: { tools: { listChanged: false } }工具列表在每次请求时固定从不发布list_changed通知因此不对外宣告该能力避免现代客户端为此建立订阅流。instructions指令OpenSEO research tools use credits. Proceed with normal focused research, but ask the user for confirmation before planned batches over 2,000 credits.—— 即 OpenSEO 研究工具消耗额度credits客户端应正常进行聚焦研究但在计划批量超过 2000 额度前须先征得用户确认。从 server.ts 可以看到当前注册的全部工具覆盖项目与项目上下文、已保存关键词、关键词研究、域名概览与关键词建议、外链概览与画像、SERP 结果、排名追踪创建/读取/增删关键词/成本估算/运行、排名关键词、SERP 竞争对手、本地商家搜索与本地 SERP、Google Business 问答/资料/评论/动态/类目/排名网格、关键词指标、Search Console 表现与 URL 检查、Google Analytics 系列工具以及网站审计系列工具。授权上下文模型每个工具调用都绑定一组授权上下文context.tsuserId、userEmail、organizationId、role、orgScope、scopes、clientId、baseUrl。其中orgScope定义了工具调用如何绑定组织pinned请求的organizationId即授权边界 —— OAuth 令牌授权时盖上组织戳与自托管模式属于此类。user凭据是用户维度的API Key—— 项目级工具从项目行推导组织并通过调用者在该组织的成员关系做授权因此一把 API Key 可用于用户所属的所有组织organizationId仅作为少数无项目参数工具的兜底上下文。Claude Code 连接对于 Claude Code官方推荐优先安装 OpenSEO 插件一条命令同时安装 MCP 与全部九个 Agent Skills。只有当你想单独使用 MCP 时才按下面的步骤操作。使用user 作用域可以让 OpenSEO 在所有项目中可用使用local 作用域则仅在当前仓库可用claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp添加服务器后按提示批准 OpenSEO 登录即可。Claude Desktop 连接Claude Desktop 不支持 Claude Code 的插件格式需要以自定义连接器connector方式添加打开Customize → Connectors。点击Add或 选择Add custom connector。粘贴https://app.openseo.so/mcp。按提示批准 OpenSEO 登录。Claude Desktop 自定义连接器在 Free、Pro、Max、Team、Enterprise 各套餐上均可用其中Free 套餐仅支持一个自定义连接器。Cursor 连接打开Cursor Settings → Tools Integrations → MCP Tools。点击New MCP ServerCursor 会打开mcp.json。添加如下配置{ mcpServers: { openseo: { url: https://app.openseo.so/mcp } } }按提示批准 OpenSEO 登录。这份mcp.json配置在仓库内的插件清单 plugins/openseo/mcp.json 中有着完全一致的等价声明可作为任何支持 mcpServers 结构的客户端的参考模板。Codex CLI 连接对于 Codex CLI官方同样推荐优先使用 OpenSEO 插件一条命令同时装上 MCP 与九个 Agent Skills。单独使用 MCP 时在终端执行codex mcp add openseo --url https://app.openseo.so/mcp按提示批准登录即可。Codex Desktop 连接打开Settings → Integrations MCP。点击Add your own。粘贴https://app.openseo.so/mcp。按提示批准 OpenSEO 登录。使用 API Key 连接无头环境与 CI在无头环境、CI 或不便走 OAuth 的客户端中使用 API Key。API Key 是个人维度的凭据任何用你的 Key 执行的操作都会以你的身份在你的工作区生效请妥善保管。在 OpenSEO 应用的Settings → API keys中创建 KeyKey 只在创建时展示一次之后不再显示请立即复制保存。Claude Code 使用 API Keyclaude mcp add --transport http --scope user openseo https://app.openseo.so/mcp --header Authorization: Bearer oseo_YOUR_KEYCursor 使用 API Key在mcp.json的服务器条目中加入headers{ mcpServers: { openseo: { url: https://app.openseo.so/mcp, headers: { Authorization: Bearer oseo_YOUR_KEY } } } }Codex CLI 使用 API Key把 Key 放入环境变量再引用避免 Key 出现在命令历史中export OPENSEO_API_KEYoseo_YOUR_KEY codex mcp add openseo --url https://app.openseo.so/mcp --bearer-token-env-var OPENSEO_API_KEY其他客户端任何支持自定义 HTTP 头的客户端都可以发送Authorization: Bearer oseo_YOUR_KEY或x-api-key: oseo_YOUR_KEY两种头之一。API Key 认证的服务端细节从源码 src/server/mcp/api-key-auth.ts 可以确认几个关键实现点Key 前缀校验服务端只认oseo_前缀的 KeyAPI_KEY_PREFIX。无论是x-api-key头还是Authorization: Bearer形式只要不以该前缀开头就会落到 OAuth 流程而不是被当作 API Key 消费从而避免误吞 Cloudflare OAuth 访问令牌等第三方凭据。调用范围API Key 走的是 verifyApiKey而不是 Better Auth 的 session 机制因此Key 永远不会变成能触达账户/组织端点的会话被严格限制在/mcp路由内。组织解析Key 按用户当前激活的组织计费但没有绑定组织若用户没有任何既有成员关系服务端会**失败关闭fail closed**返回 403绝不会为 API Key 凭空铸造默认组织。限流托管生产环境通过 Cloudflare 速率限制绑定MCP_RATE_LIMIT按用户限流达到上限返回 429并带Retry-After响应头。错误语义响应体使用 OAuth 风格的错误码 ——rate_limited/usage_exceeded429、account_access_revoked403如 Key 不再关联组织、invalid_api_key401Key 无效、过期或已禁用。连接背后的 OAuth 授权流程无论走哪种客户端交互式登录背后都是同一套 OAuth 授权src/server/mcp/oauth-provider.ts标准端点授权端点/api/auth/oauth2/authorize、令牌端点/api/auth/oauth2/token、动态客户端注册DCR端点/api/auth/oauth2/register以及应用内的同意页/oauth-consent。授权范围MCP_OAUTH_SCOPES [offline_access, mcp]见 src/lib/oauth-resource.ts。offline_access用于换取刷新令牌以维持长期会话mcp是调用 MCP 资源的必需范围缺失mcp范围会被直接拒绝。令牌生命周期访问令牌 TTL 为 24 小时刷新令牌 TTL 为 30 天动态注册的客户端记录 TTL 为一年使活跃刷新中的客户端不会因客户端记录过期而突然失效。逐请求校验成员关系授权令牌会快照organizationId且刷新时原样复制 —— 因此授权可能比成员关系活得更久成员被移除、组织变更等。托管传输层在每个请求重新查询成员表transport.ts成员关系失效时返回 401invalid_token推动兼容客户端重新走 OAuth在同意页盖上当前组织的戳。Origin 校验托管端先做精确的 Origin 校验仅接受托管域与 Surfmin 扩展 Origin再传入主机名白名单作为纵深防御自托管端不设置白名单交由 SDK 的 localhost 类默认处理transport.ts。可用工具一览OpenSEO MCP 为 SEO 研究工作流暴露了下列工具能力研究关键词含搜索量、难度与 CPC。获取关键词的实时 Google 自然 SERP 结果。查找某域名或页面的精确关键词、排名、搜索量、CPC、搜索意图与流量数据行。在给定关键词集合上对比 SERP 竞争对手。按坐标搜索附近本地商家可按评分、评论数或认领状态过滤。获取一个 Maps 或 Local Finder SERP需要时读取 Google Business 问答。审计 Google Business Profile类目、评分、营业时间、照片与认领状态。收集 Google 评论含其他站点评论与 Google Business 动态。查询合法的 Google Business 类目 slug。在商家周围的网格各点检查 Google Maps 排名。为关键词补充搜索量、难度、意图、CPC 与趋势数据。列出 OpenSEO 项目中的已保存关键词。将有用的关键词保存回 OpenSEO。读取排名追踪配置与最新关键词排名。汇总域名的自然流量足迹。查找域名已获得排名的关键词。检查外链与引用域名概览数据。读取第一方 Google Search Console 表现数据点击、展示、CTR、排名。检查特定 URL 的索引状态、抓取与 canonical单次调用最多 10 个 URL。读取与更新项目的共享上下文业务、目标、定位、写作偏好、竞争对手、关键页面与研究日志免费不消耗额度。一个实用的配合模式当 Agent 找不到项目时先调用list_projects列出 OpenSEO 项目再把返回的projectId用于后续工具调用。从 list-projects.ts 的实现看该工具不消耗额度不调用 DataForSEO并会返回每个项目的id、name、domain、locationCode、languageCode其中 location/language 是项目的默认市场当调用省略位置/语言参数时工具会自动回退到它们。连接完成后的下一步Agent SkillsMCP 连接完成只是第一步。MCP 赋予你的 Agent 访问 OpenSEO 数据的能力而Agent Skills 是独立的SKILL.md文件告诉 Agent 如何为特定 SEO 任务使用这些数据。两者是分离的详见 Set up OpenSEO Agent Skills。建议从一个聚焦的工作流开始而不是笼统地让 Agent 做 SEO用 SEO 项目设置 把目标、定位、竞争对手与关键页面存入项目上下文供其他所有技能复用。如果你是 SEO 新手、不确定先跑哪个工作流用 SEO 教练。用 关键词研究 发掘关键词机会。用 竞争格局 在选择竞争对手或页面之前先摸清市场。用 竞争对手分析 研究单个竞争对手。用 关键词聚类 把关键词组织成页面分组。用 外链机会挖掘 为可链接资产寻找外展对象。如果你在使用 Claude CodeOpenSEO 插件 一次安装即可同时获得 MCP 与全部九个 SkillsSEO Project Setup、SEO Coach、SEO Audit、Keyword Research、Keyword Clustering、Competitive Landscape、Competitor Analysis、Local SEO、Link Prospecting插件内技能以/openseo:前缀命名空间调用。故障排查无法连接确认服务器 URL 严格等于https://app.openseo.so/mcp不要有多余字符或路径。Codex 报Authorization server response missing required issuer: expected https://app.openseo.so这是 Codex 0.143 至 0.146 版本的已知问题 —— 这些版本会在 OAuth 回调中丢弃 issuer。请将 Codex CLI 或 Codex 桌面应用升级到0.147.0 或更高也可以改用上文 API Key 连接 绕过 OAuth。授权失败在客户端中断开 OpenSEO 服务器重新添加并重走一遍登录流程。Agent 找不到项目让 Agent 先列出 OpenSEO 项目再使用返回的projectId进行后续工具调用见上文list_projects说明。延伸阅读Set up OpenSEO MCP本文对应的官方文档原文Install the OpenSEO plugin for Claude CodeSet up OpenSEO Agent Skills服务端实现src/server/mcp/server.ts、src/server/mcp/transport.ts、src/server/mcp/oauth-provider.ts、src/server/mcp/api-key-auth.ts、src/server/mcp/context.ts插件清单示例plugins/openseo/mcp.json【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考