API 与 MCP 文档

关键词难度估算(哥飞版)提供三个入口：网页（人工查询）、MCP（AI 客户端调用）、HTTP API（脚本与自动化）。三端共用同一个令牌、同一个每日额度池、同一条计算管线与缓存。

← 返回工具

1. 获取令牌

使用 Web.Cafe 登录后，在下方一键生成专属令牌（wc_mcp_ 前缀）。令牌明文仅显示一次，服务端只保存哈希；遗失可随时重置，旧令牌立即作废。同一个令牌通用于 MCP 与 HTTP API，额度与网页查询共用。

2. 额度规则

网页查询、MCP 调用、API 调用合并计入同一额度。另有每分钟 10 次的瞬时保险丝（仅 MCP/API），防止批量调用瞬间打爆上游。7 天内重复查询同一关键词命中缓存，同样计入额度但秒级返回。

3. HTTP API

端点

GET https://seo.web.cafe/kd/api/v1/kd

鉴权（二选一）

• 请求头：Authorization: Bearer wc_mcp_你的令牌（推荐）
• 查询参数：&token=wc_mcp_你的令牌（适合不便设置 Header 的场景；URL 即凭证，注意保管）

参数

示例

# curl（JSON）
curl "https://seo.web.cafe/kd/api/v1/kd?keyword=ai+photo+editor&gl=us" \
  -H "Authorization: Bearer wc_mcp_你的令牌"

# curl（Markdown 报告）
curl "https://seo.web.cafe/kd/api/v1/kd?keyword=ai+photo+editor&format=markdown&token=wc_mcp_你的令牌"

# Python 批量选词
import requests, time

TOKEN = "wc_mcp_你的令牌"
words = ["ai photo editor", "ai logo maker", "pdf to excel"]

for kw in words:
    r = requests.get(
        "https://seo.web.cafe/kd/api/v1/kd",
        params={"keyword": kw, "gl": "us"},
        headers={"Authorization": "Bearer " + TOKEN},
        timeout=30,
    )
    d = r.json()
    if r.status_code != 200:
        print(kw, "→ 失败:", d.get("error")); continue
    print(kw, "→", d["score"], d["level"],
          "| 类型:", d["keywordType"],
          "| 预算中值:", d["linkBudget"]["quality"]["mid"] if d.get("linkBudget") else "—")
    time.sleep(6)  # 配合每分钟 10 次的保险丝

// Node.js / JavaScript
const TOKEN = "wc_mcp_你的令牌";
const resp = await fetch(
  "https://seo.web.cafe/kd/api/v1/kd?keyword=" + encodeURIComponent("ai photo editor") + "&gl=us",
  { headers: { Authorization: "Bearer " + TOKEN } }
);
const d = await resp.json();
console.log(d.score, d.level, d.reasons[0]);

返回字段（JSON）

details 行字段

错误码

4. MCP（Model Context Protocol）

把难度估算注册为 AI 客户端的工具，AI 即可在对话中自主调用——「帮我从这 20 个词里挑 3 个最值得做的」会自动逐个查询并对比。工具名 estimate_keyword_difficulty，参数 keyword（必填）、gl / hl / force（可选），返回完整 Markdown 报告。

Claude Code

claude mcp add --transport http kd-gefei https://seo.web.cafe/kd/mcp \
  --header "Authorization: Bearer wc_mcp_你的令牌"

Claude.ai 网页版 / Claude Desktop（Add custom connector）

URL 填带令牌的地址，Advanced settings 两个 OAuth 框全部留空（那是 OAuth 专用字段，填令牌会报 "A client id must be provided with a client secret"）：

https://seo.web.cafe/kd/mcp?token=wc_mcp_你的令牌

其他 MCP 客户端（Cursor 等）

传输方式 Streamable HTTP，端点 https://seo.web.cafe/kd/mcp；支持自定义 Header 的客户端加 Authorization: Bearer 令牌，不支持的用上面带 ?token= 的 URL。

5. 模型口径速览

• 站点强度 = 0.6×DR + 0.4×流量分（对数归一化）；普通内页按 45% 折算、专门经营页面按 65% 折算、首页全额计入，位置加权汇总
• 信号体系：弱站/弱首页、专门经营密度、强首页密度、首页拥挤度、Top3 封锁、主力词密度、体量先验、上升期趋势、盘面体验脆弱度、新域名信号、域名迁移识别
• 品牌词自动切换口径：剔除品牌本尊与平台生态页（固定位），只对可竞争位计分，回答「第三方以衍生内容进入此 SERP 的难度」
• 链接预算按 Ahrefs 官方 KD→引用域曲线由最终难度分插值，口径为进入前十所需；编辑型 / 目录型双轨
• 结果仅供选词参考，不构成排名保证

← 返回工具