Oncrawl MCP Server

OnCrawl MCP服务器

](https://badge.fury.io/py/oncrawl-mcp-server) 

MCP服务器，用于公开OnCrawl的API，以便与Claude Code和Claude Desktop一起使用。使Claude能够通过查询爬网数据、Google Search Console指标和爬网比较来执行深入的技术SEO分析。

特性

• 12个MCP工具 进行全面的SEO分析
• 原始数据访问：使用灵活的OQL查询页面、链接、集群、结构化数据
• 架构发现：Claude在查询之前学习可用字段
• 聚合：按任何维度分组/计数以进行模式检测
• 全部出口：完整数据集没有10k的限制
• 爬行分析：跟踪抓取之间的更改（新页面、状态更改等）
• 谷歌搜索控制台集成：600多个GSC字段，包括点击、展示、点击率、设备位置、品牌/非品牌等
• 谷歌分析4集成：会话、用户和参与度指标

是什么让它如此强大

OnCrawl将爬网数据与GSC/GA4流量数据相结合，实现了以下分析：

• 有流量的孤立页面：页面从谷歌获得点击，但内部没有链接
• 突出显示高绩效者：内部链接较弱的热门页面
• 低CTR机会：展示率高但点击率低的页面
• 404还在谷歌：搜索结果中仍出现损坏的页面
• 有流量的深度页面：谷歌重视的隐藏内容
• 移动与桌面性能：按设备划分的流量明细

先决条件

• Python 3.11+
• 具有API访问权限的OnCrawl帐户
• OnCrawl API令牌（来自您的OnCrawl设置）

安装

选项1：从PyPI安装（推荐）

pip install oncrawl-mcp-server

然后在Claude Desktop/Code中进行配置（请参阅 配置).

选项2：从源代码安装

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Mac/Linux
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -e .

获取您的API代币

1. 登录OnCrawl
2. 首选 设置→ API
3. 使用创建新令牌 projects:read 范围
4. 复制令牌

获取您的工作区ID

列出项目需要您的工作区ID。要找到它：

1. 登录OnCrawl
2. 请查看浏览器中的URL，其格式如下：

   https://app.oncrawl.com/workspace/5c015889451c956baf7ab7a9/projects
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^
                                   This is your workspace ID

1. 从URL复制24个字符的ID

为了方便起见，您可以选择将其添加到配置中，或者在调用工具时直接传递它。

配置

适用于克劳德桌面

窗户： 编辑 %APPDATA%\Claude\claude_desktop_config.json 雨衣： 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "oncrawl": {
      "command": "python",
      "args": ["-m", "oncrawl_mcp_server.server"],
      "env": {
        "ONCRAWL_API_TOKEN": "your-api-token-here",
        "ONCRAWL_WORKSPACE_ID": "your-workspace-id-here"
      }
    }
  }
}

备注: ONCRAWL_WORKSPACE_ID 是可选的，但为方便起见建议使用。如果没有设置，您需要在呼叫时提供它 oncrawl_list_projects.

克劳德代码（CLI）

# Add to your MCP config
claude mcp add oncrawl

# Or manually edit your config with:
{
  "mcpServers": {
    "oncrawl": {
      "command": "python",
      "args": ["-m", "oncrawl_mcp_server.server"],
      "env": {
        "ONCRAWL_API_TOKEN": "your-api-token-here",
        "ONCRAWL_WORKSPACE_ID": "your-workspace-id-here"
      }
    }
  }
}

备注: ONCRAWL_WORKSPACE_ID 是可选的，但为方便起见建议使用。

重要：更改配置后重新启动Claude Desktop/Code。

可用工具

处理大型结果集

OnCrawl API将每个请求的搜索结果限制为10000个。对于较大的数据集：

• oncrawl_search_all_pages / oncrawl_search_all_links：自动分页所有结果
• 使用 max_results 用于限制总数的参数（例如。， max_results: 50000)
• 对于非常大的导出（100k+），考虑使用过滤器来减少数据集

使用示例

入门指南

"List my OnCrawl projects"
# If ONCRAWL_WORKSPACE_ID is not set in config, specify it:
"List my OnCrawl projects in workspace 5c015889451c956baf7ab7a9"

"Get the schema for crawl xyz789 - what fields are available?"

"Show me the first 10 pages from this crawl"

SEO技术分析

"Find all pages at depth > 5 with fewer than 3 inlinks"

"Show me 404 pages that still have internal links pointing to them"

"What's the status code distribution for this crawl?"

"Find pages with missing meta descriptions"

GSC集成

"Find orphan pages (0 internal links) that are getting clicks from Google"

"Show me pages with high impressions but low CTR (<2%)"

"Which pages buried deep in the site are getting significant traffic?"

"Compare mobile vs desktop traffic for the top landing pages"

爬行分析

"Show me pages that changed status code between the last two crawls"

"Find pages that were added in the latest crawl"

"Which pages increased in depth between crawls?"

"Show me the status code distribution changes over time"

侦探工作

"I want you to act as a senior SEO analyst. Investigate crawl xyz789 for issues:
- Site structure problems
- Orphan page clusters
- Broken internal links
- Pages that should be linked better
- Anything else that looks problematic"

"Analyze this site for low-hanging SEO opportunities using both crawl and GSC data"

OQL查询语言

OnCrawl使用OQL（OnCrawl查询语言）进行过滤。以下是关键运算符：

基本运算符

// Equals
{"field": ["status_code", "equals", 200]}

// Greater than / Less than
{"field": ["depth", "gt", "3"]}
{"field": ["follow_inlinks", "lt", "5"]}

// Contains
{"field": ["url", "contains", "/blog/"]}

// Starts with
{"field": ["urlpath", "startswith", "/products/"]}

// Has value / No value
{"field": ["canonical", "has_value", ""]}
{"field": ["canonical", "has_no_value", ""]}

组合过滤器

// AND
{
  "and": [
    {"field": ["status_code", "equals", 200]},
    {"field": ["depth", "gt", "3"]},
    {"field": ["follow_inlinks", "lt", "5"]}
  ]
}

// OR
{
  "or": [
    {"field": ["status_code", "equals", 301]},
    {"field": ["status_code", "equals", 404]}
  ]
}

// Nested combinations
{
  "and": [
    {"field": ["status_code", "equals", 200]},
    {
      "or": [
        {"field": ["depth", "gt", "5"]},
        {"field": ["follow_inlinks", "equals", 0]}
      ]
    }
  ]
}

正则表达式支持

{"field": ["urlpath", "startswith", "/blog/[0-9]{4}/", {"regex": true}]}

常用字段名称

爬行场

• url, urlpath, depth, status_code
• follow_inlinks, follow_outlinks
• title, description, h1, canonical
• content_length, load_time
• indexability, is_compliant

GSC字段（600+可用）

• gsc_clicks, gsc_impressions, gsc_ctr, gsc_position
• gsc_clicks_device_mobile, gsc_clicks_device_desktop
• gsc_clicks_brand, gsc_clicks_nonbrand
• gsc_impressions_device_mobile等等。

谷歌分析字段

• google_analytics_users_seo
• google_analytics_sessions_seo
• google_analytics_engaged_sessions_seo
• google_analytics_engagement_rate_seo

专业建议：总是打电话 oncrawl_get_schema 首先，看看哪些字段可用于您的特定爬网。

GSC集成

当连接到您的帐户时，OnCrawl会自动与Google Search Console集成。如果集成处于活动状态，GSC字段将出现在架构中。

它是如何工作的：

• 如果GSC已连接：架构中有600多个GSC字段可用
• 如果GSC未连接：GSC字段将不会出现在架构中
• 查询没有集成的GSC字段会返回400错误
• 没有数据的字段返回0或null（不是错误）

检测： 请先检查架构 oncrawl_get_schema 查看GSC字段是否存在。

故障排除

“需要ONCRAWL_API_TOKEN环境变量”

• 确保令牌已设置在 env MCP配置块
• 更改配置后重新启动Claude Desktop/Code

“未知字段”错误

• 呼叫 oncrawl_get_schema 首先查看可用字段
• 字段名区分大小写
• GSC字段仅在GSC集成处于活动状态时显示

API费率限制

• OnCrawl API有速率限制
• 如果出现429个错误，请减慢请求速度
• 对大型数据集使用导出而不是分页

工具未出现在Claude中

• 验证配置中的Python路径是否正确
• 检查是否安装了oncrawl mcp服务器
• 查看Claude的MCP连接错误日志
• 配置更改后重新启动Claude

权限错误

• 验证API令牌是否具有 projects:read 范围
• 检查工作区/项目/爬网ID是否正确

发展

运行测试

# Set your API token
export ONCRAWL_API_TOKEN="your-token"

# Run the server directly
python -m oncrawl_mcp_server.server

# Test with a specific project
python test_full_mcp.py

从源头构建

# Install build tools
pip install build twine

# Build the package
python -m build

# Install locally
pip install -e .

版本历史

0.2.0（最新）

• 添加了3个爬行（COC）工具
• 总计12个MCP工具
• 完整的GSC集成文档

0.1.0

• 初始版本包含9个核心工具
• 基本OnCrawl API集成

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

链接

• 报告问题
• OnCrawl文档
• 模型上下文协议

作者

安东尼奥-