DataLens 抓取技能

工具调用机制说明

每个 DataLens 工具均通过执行终端命令来调用，无需配置 MCP 客户端。

datalens-mcp-call 二进制程序负责完成 MCP stdio 握手，并将工具执行结果以 YAML/JSON 格式输出至 stdout。

run_in_terminal: datalens-mcp-call  ''

若 datalens-mcp-call 不在系统 PATH 中（例如未全局安装），可使用 npx：

run_in_terminal: npx datalens-mcp-call  ''

前提条件

1. 已安装 datalens-mcp-server npm 包：npm install -g datalens-mcp-server（或直接使用 npx）。
2. 已在 Chrome 中安装并启用 DataLens 浏览器扩展。
3. Chrome 已打开且目标页面已加载（或在工具参数中提供 url，扩展将自动打开该页面）。
4. 终端中可用的 Node.js 版本 ≥ 18。

工作原理

datalens-mcp-call 启动 DataLens MCP 代理作为子进程，通过 stdio 完成 MCP 初始化握手，调用指定工具，并打印执行结果。

AI Agent
  ↓ run_in_terminal
datalens-mcp-call  
  ↓ stdio JSON-RPC
DataLens MCP Proxy (datalens-mcp-proxy)
  ↓ WebSocket (localhost:17373)
Chrome Extension
  ↓
Browser Tab

标准抓取流程

请严格按以下步骤顺序执行。不得跳过任一环节，且不可在 scrape_analyze_columns 完成前调用 scrape_start。

步骤 1 — 检测表格

datalens-mcp-call scrape_detect_tables '{"url":"https://example.com","prompt":"article list"}'

返回检测到的表格结构列表，包含 rootSelector、itemSelector 和 documentInfoPath 字段。请选择最匹配的表格，并复制这三个值供后续步骤使用。

若页面需登录，请先提示用户在 Chrome 中完成登录，再重新运行此命令。

步骤 2（可选）— 检查 DOM 树中的展开按钮

datalens-mcp-call scrape_get_table_tree '{"rootSelector":"","itemSelector":"","documentInfoPath":""}'

当数据存在嵌套回复、折叠行或“加载更多”按钮时使用。请检查输出中带 _uid 注解的树结构，识别出对应展开按钮的 UID。

步骤 2b（可选）— 点击展开并重新检测

datalens-mcp-call scrape_click_expand_and_redetect '{"rootSelector":"...","itemSelector":"...","documentInfoPath":"...","expandButtonUids":[{"type":"reply","uids":["uid1","uid2"]}]}'

扩展程序将点击对应按钮，等待新内容加载完毕后重新执行检测。请使用本次输出中更新后的 rootSelector/itemSelector/documentInfoPath 进入步骤 3。

步骤 3 — 分析列字段

datalens-mcp-call scrape_analyze_columns '{"rootSelector":"...","itemSelector":"...","documentInfoPath":"...","url":"https://example.com","prompt":"article list"}'

调用后端 AI 识别字段名、数据类型及分页逻辑，返回 scraperConfig 和 jobDraft。请确认字段列表无误后再继续下一步。

步骤 4 — 启动抓取任务

# 传入 scrape_analyze_columns 返回的 jobDraft 对象
datalens-mcp-call scrape_start '{"jobDraft":,"maxRecords":10}'

返回一个 jobId。首次运行建议使用 maxRecords: 10 进行预览验证。

步骤 5 — 轮询任务状态

datalens-mcp-call scrape_status '{"jobId":"","waitMs":3000}'

重复执行该命令，直至 status 变为 COMPLETED、FAILED 或 STOPPED。

关键状态字段说明：

• status：状态流转为 QUEUED → PREPARING → RUNNING → COMPLETED / FAILED / STOPPED
• scrapedCount：当前已采集的行数
• error：仅在失败时存在

步骤 6 — 获取结果

保存至文件（推荐用于大数据集）：

datalens-mcp-call scrape_export_to_file '{"jobId":"","outputDir":"/tmp/datalens","format":"json"}'

返回保存的文件路径。

内联预览（适用于小数据集）：

datalens-mcp-call scrape_result '{"jobId":"","limit":50}'

每次响应中的 cursor 字段可用于获取下一页数据。

内存导出（不落地）：

datalens-mcp-call scrape_export '{"jobId":"","format":"csv"}'

返回 base64 编码的文件内容。

任务控制

datalens-mcp-call scrape_pause  '{"jobId":""}'
datalens-mcp-call scrape_resume '{"jobId":""}'
datalens-mcp-call scrape_stop   '{"jobId":""}'

浏览器标签页管理

datalens-mcp-call browser_list_tabs
datalens-mcp-call browser_open_tab  '{"url":"https://example.com"}'
datalens-mcp-call browser_use_tab   '{"tabId":123}'
datalens-mcp-call browser_close_tab '{"tabId":123}'

通常无需手动管理标签页——当 scrape_detect_tables 的参数中包含 url 时，扩展会自动打开对应标签页。

Agent 决策规则

• 严禁在未获得 scrape_analyze_columns 响应返回的 jobDraft 或 scraperConfig 的情况下调用 scrape_start。自行构造 scraperConfig 将导致错误结果。
• 严禁跳过 scrape_analyze_columns 直接调用 scrape_start。分析步骤是生成有效配置的必要前提。
• 若 scrape_detect_tables 返回空列表，可能因页面需要登录或内容为动态加载。请提示用户在 Chrome 中手动打开目标 URL 并滚动页面以触发内容加载，然后重试。
• 若 scrape_status 在 QUEUED 状态持续超过 30 秒，请检查 Chrome 扩展是否处于激活状态，以及目标 URL 对应的标签页是否已打开。
• 建议始终先使用 maxRecords: 10 运行预览抓取，确认配置正确后再执行完整任务。
• 默认导出格式为 JSON。当用户明确要求电子表格格式输出时，可选用 CSV 或 XLSX。

端到端示例：抓取今日头条头条新闻标题

# 1. 在首页检测表格
datalens-mcp-call scrape_detect_tables '{"url":"https://www.toutiao.com/?is_new_connect=0&is_new_user=0","prompt":"article list"}'

# 2. 分析列字段（将步骤 1 输出中的 selectors 填入）
datalens-mcp-call scrape_analyze_columns '{"rootSelector":"","itemSelector":"","documentInfoPath":"","url":"https://www.toutiao.com/?is_new_connect=0&is_new_user=0","prompt":"article list"}'

# 3. 预览运行 — 获取前 10 行（将步骤 2 返回的完整 jobDraft JSON 对象粘贴至此）
datalens-mcp-call scrape_start '{"jobDraft":,"maxRecords":10}'

# 4. 轮询状态直至 COMPLETED
datalens-mcp-call scrape_status '{"jobId":"","waitMs":3000}'

# 5. 将结果保存至文件
datalens-mcp-call scrape_export_to_file '{"jobId":"","outputDir":"/tmp/datalens","format":"json"}'

若某次工具调用耗时超过默认的 120 秒，可在执行前设置超时环境变量：DATALENS_TIMEOUT=180000

DATALENS_TIMEOUT=180000 datalens-mcp-call scrape_analyze_columns '...'

调试工具

仅限故障排查使用，正常抓取流程中请勿调用。

datalens-mcp-call debug_get_logs '{"levels":["error"]}'
datalens-mcp-call debug_clear_logs '{}'
datalens-mcp-call debug_export_logs_to_file '{"outputDir":"/tmp/datalens"}'