# MCP、Skills 与 SDK

除了直接发 HTTP 请求，还有三种官方开源的接入方式：给 AI 助手用的 MCP 服务、给 agent 用的 Agent Skills、给自己代码用的 TypeScript / Python SDK。三者都只需要一个环境变量 DATAFORGEO_API_KEY，扣费规则和直接调用 API 完全相同。

| 方式 | 适合 | 安装 |
| --- | --- | --- |
| MCP 服务 | 让 Claude、Cursor 等 AI 助手直接拿到查询工具 | `npx -y @dataforgeo/mcp` |
| Agent Skills | 让 agent 按工作流完成体检、竞品对比、引用分析和周报 | `/plugin install dataforgeo@dataforgeo` |
| SDK | 在自己的 TypeScript / Python 代码里集成 | `npm install @dataforgeo/client` |

### MCP 服务

给 Claude Code、Claude Desktop、Cursor、Windsurf 等支持 MCP 的 AI 助手加上 6 个工具。stdio 传输，npx 直接运行，需要 Node.js 20 或以上。每个工具的描述里都写明了扣费规则，助手调用前就知道要花多少 credits。

```bash
claude mcp add dataforgeo -e DATAFORGEO_API_KEY=$DATAFORGEO_API_KEY -- npx -y @dataforgeo/mcp
```

```json
{
  "mcpServers": {
    "dataforgeo": {
      "command": "npx",
      "args": [
        "-y",
        "@dataforgeo/mcp"
      ],
      "env": {
        "DATAFORGEO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

| tool | API | 说明 | 扣费 |
| --- | --- | --- | --- |
| `geo_answer` | POST /v1/geo/answer | 一个 prompt 在多个引擎上的答案，标出品牌提及、引用和竞品 | 同 API |
| `geo_index` | POST /v1/geo/index | 同上，并计算 GEO Index KPI（Pro 及以上） | 同 API |
| `geo_index_summary` | GET /v1/geo/index/summary | 已跑结果的 KPI、趋势和维度拆分 | 0 |
| `get_job` | GET /v1/jobs/{job_id} | 查询异步任务，可用 wait_seconds 等待完成 | 0 |
| `get_account` | GET /v1/account | 档位、余额、本月用量 | 0 |
| `estimate_credits` | 本地计算 | 估算一次或一批调用最多预占多少 credits，不发请求 | 0 |

| 环境变量 | 必填 | 说明 |
| --- | --- | --- |
| `DATAFORGEO_API_KEY` | 是 | API key，作为请求头 x-api-key 发送 |
| `DATAFORGEO_BASE_URL` | 否 | 覆盖 API 地址 |
| `DATAFORGEO_MAX_CREDITS_PER_CALL` | 否 | 单次 geo_answer / geo_index 最多预占的 credits，超过则本地拒绝、不发请求。推荐给自动化 agent 设置 |

https://github.com/DataForGEO/mcp

### Agent Skills

开箱即用的 GEO 工作流，适用于 Claude Code、Claude.ai 以及其他支持 Agent Skills 的 agent（Codex CLI、Cursor、Gemini CLI 等）。会花 credits 的 skill 都会先查余额、估算预占，征得你同意后才批量调用。每个 skill 自带零依赖的命令行工具 dfgeo.py，只需 Python 3.8+。

```text
/plugin marketplace add DataForGEO/skills
/plugin install dataforgeo@dataforgeo
```

| skill | 说明 | 花 credits |
| --- | --- | --- |
| `dataforgeo-api` | 基础：单次调用 answer / index / summary、查余额、估算 credits、取异步任务 | 按调用 |
| `geo-prompt-set-builder` | 按意图 × 人群 × 语言设计要追踪的 prompt 集，输出 JSONL 并估算成本 | 否 |
| `geo-visibility-audit` | 品牌 AI 可见度体检：批量跑 prompt × 引擎，出带依据和行动建议的报告 | 是，先估算并征得同意 |
| `geo-competitor-benchmark` | 竞品对比：声量份额、首推率、平均位次、逐 prompt 胜负 | 是，同上 |
| `geo-citation-audit` | 引用来源分析：AI 引用了哪些站点、自有来源引用率、内容 / 外联 / PR 清单 | 可复用已有结果，不额外扣费 |
| `geo-index-report` | GEO Index 周报 / 月报，并搭建固定 tag 的每周追踪 | 报告否；追踪按调用 |

Claude.ai / Claude Desktop：在仓库里运行 python3 scripts/package.py 生成 zip，到 设置 → 功能 → Skills 上传，并开启代码执行。Skills 和 MCP 可以一起用。

https://github.com/DataForGEO/skills

### SDK

TypeScript / JavaScript 包 @dataforgeo/client，Python 包 dataforgeo。

```bash
npm install @dataforgeo/client
pip install dataforgeo
```

```ts
import { DataForGEO } from "@dataforgeo/client";

const client = new DataForGEO(); // reads DATAFORGEO_API_KEY
const res = await client.geo.answer({
  prompt: "东京有哪些适合家庭入住的民宿？",
  engines: ["chatgpt"],
  brand: "晓宅",
  location: "JP",
  language: "zh-CN",
});
console.log(res.answers[0].brand?.mentioned, res._meta.creditsRemaining);
```

```python
from dataforgeo import DataForGEO

client = DataForGEO()  # reads DATAFORGEO_API_KEY
res = client.geo.answer(
    prompt="东京有哪些适合家庭入住的民宿？",
    engines=["chatgpt"],
    brand="晓宅",
    location="JP",
    language="zh-CN",
)
print(res["answers"][0]["brand"]["mentioned"], res.meta.credits_remaining)
```

- 两个 SDK 的接口一一对应，覆盖全部接口、错误码、用量响应头（x-credits-used 等）、异步任务和 webhook 签名校验。
- 请求参数和响应字段与 API 一致（snake_case），不做转换。
- 429、408、5xx 自动重试（错误响应不扣费）；网络错误只重试 GET，POST 不重试以免重复扣费。

https://github.com/DataForGEO/client