Pangolinfo MCP

🛒 Pangolinfo MCP 服务器

通过 Model Context Protocol 为 AI 助手提供 18 款亚马逊电商与知识产权数据工具。

🔗 官方网站：www.pangolinfo.com

将你常用的 AI 客户端（Claude Code、Cursor、Cline、Windsurf、Codex、Hermes、OpenClaw）接入 Pangolinfo 的亚马逊抓取 API，让 AI 从自然语言指令出发，运行实时广告追踪、Sponsored Products 分析、VOC 情感分析、关键词监控和竞品产品审计 —— 以及关键词研究、Listing 分析、评论挖掘、细分市场发现、类目导航、AI 搜索查询、关键词趋势检查与 WIPO 商标清查等能力。

⚠️ 0.7.0 重大变更 —— pacer_search 已停用，合并进 wipo_search

独立的 pacer_search 工具已被移除。现在通过向 wipo_search 传入 enableLitigation=true 即可查询美国专利诉讼（PACER）信息 —— 它在一次调用中查找专利并关联相关的美国诉讼案件。仍固定使用 pacer_search 的提示词/脚本会收到 ToolNotFound；请改用带 enableLitigation 的 wipo_search。

更早的重大变更（0.3.0 —— 工具重命名）

旧名称（≤ 0.2.x）	新名称（0.3.0+）
google_ai_search	ai_search
google_trends	keyword_trends

工具名称的变更旨在从公开的 MCP 接口中移除第三方品牌引用。工具参数、返回结构和定价保持不变。

版本	0.7.3
工具	18 款业务工具（外加一个免费的本地 pangolinfo_capabilities 自省调用）
传输方式	stdio（本地） · streamable HTTP（托管 —— 见下文）
运行时	Node.js 18+
许可证	MIT
获取 API Key	https://tool.pangolinfo.com/#/en/system/loading?sourceTag=github_amz

---

📦 安装

推荐：一行安装器（覆盖 7 种 AI 客户端）

Pangolinfo Installer 会自动识别你的 AI 客户端、写入正确的配置文件，一步到位。传入 --scope=mcp 可仅安装本 MCP 服务器（跳过 Skills 包）。

macOS / Linux

curl -fsSL https://pangolinfo.dev/install.sh | sh -s -- \
  --agent=<your-agent> \
  --scope=mcp \
  --api-key=pgl_xxxxxxxxxxxx

Windows（PowerShell）

irm https://pangolinfo.dev/install.ps1 | iex; `
  Install-Pangolinfo -Agent <your-agent> -Scope mcp -ApiKey pgl_xxxxxxxxxxxx

<your-agent> 为以下之一：claude-code、cursor、cline、windsurf、codex、hermes、openclaw。

安装器完成后，请重启你的 AI 客户端，以使其加载新的 mcpServers 条目。

手动安装（只需下载一个文件）

发布产物是一个自包含的单一 server.mjs（约 800 KB）—— 所有依赖已内置，无需 npm install。

# macOS / Linux
mkdir -p ~/.local/lib/pangolinfo-mcp
curl -fsSL https://github.com/pangolinfo/pangolinfo-mcp/releases/latest/download/server.mjs \
  -o ~/.local/lib/pangolinfo-mcp/server.mjs
chmod +x ~/.local/lib/pangolinfo-mcp/server.mjs

# Windows (PowerShell)
$dir = "$env:LOCALAPPDATA\pangolinfo-mcp"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
irm https://github.com/pangolinfo/pangolinfo-mcp/releases/latest/download/server.mjs `
  -OutFile "$dir\server.mjs"

然后将其接入你的 AI 客户端 —— 参见下方各客户端的配置片段。将 args 指向你刚下载的文件即可。

开发者：如需从源码构建，请 git clone 本仓库并运行 npm install && npm run build。生成的 dist/server.mjs 与发布产物完全一致。

---

🔑 获取 API Key

1. 在 https://tool.pangolinfo.com/#/en/system/loading?sourceTag=github_amz 注册账号
2. 从控制台复制你的 pgl_xxxxxxxx 密钥
3. 如有需要，充值额度（每次亚马逊抓取调用消耗 0.75 credits；pangolinfo_capabilities 免费）

---

⚙️ 手动配置（各 AI 客户端）

请将 /abs/path/to/pangolinfo-mcp/dist/server.mjs 替换为你的真实路径，并将 pgl_xxxxxxxx 替换为你的密钥。

Claude Code（~/.claude/settings.json）

{
  "mcpServers": {
    "pangolinfo": {
      "command": "node",
      "args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
      "env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
    }
  }
}

推荐使用 claude mcp add --scope user pangolinfo node /abs/path/to/dist/server.mjs —— 它会写入相同的条目，无需手动编辑 JSON。

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "pangolinfo": {
      "command": "node",
      "args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
      "env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
    }
  }
}

Cline（VS Code 扩展）

打开 Cline → MCP Servers → Edit settings JSON，然后添加：

{
  "mcpServers": {
    "pangolinfo": {
      "command": "node",
      "args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
      "env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
    }
  }
}

配置文件位于 <vscode-user>/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json。 如果你使用的是独立的 Cline CLI，请改用 ~/.cline/data/settings/cline_mcp_settings.json。

Windsurf（~/.codeium/windsurf/mcp_config.json）

{
  "mcpServers": {
    "pangolinfo": {
      "command": "node",
      "args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
      "env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.pangolinfo]
command = "node"
args = ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"]

[mcp_servers.pangolinfo.env]
PANGOLINFO_API_KEY = "pgl_xxxxxxxx"

Hermes（~/.hermes/config.yaml）

mcp_servers:
  pangolinfo:
    command: node
    args: ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"]
    env:
      PANGOLINFO_API_KEY: pgl_xxxxxxxx

OpenClaw（~/.openclaw/openclaw.json）

{
  "mcpServers": {
    "pangolinfo": {
      "command": "node",
      "args": ["/abs/path/to/pangolinfo-mcp/dist/server.mjs"],
      "env": { "PANGOLINFO_API_KEY": "pgl_xxxxxxxx" }
    }
  }
}

---

☁️ 托管模式（远程 HTTP）—— 无需本地安装

不想安装任何东西？将 AI 客户端指向托管的端点，而不是本地 server.mjs。这是 streamable HTTP 传输方式（MCP 规范），支持多租户 —— 每次请求都携带你自己的密钥。

端点	https://mcp.pangolinfo.com/mcp
传输方式	Streamable HTTP（POST + SSE）
认证方式	你的 pgl_xxxxxxxx 密钥，通过 Bearer 请求头或 URL 查询参数传递

传递 API Key 的两种方式

1. Authorization 请求头（推荐）

Authorization: Bearer pgl_xxxxxxxx

这是首选方式：密钥不会出现在 URL、日志和浏览器历史中。Bearer 方案不区分大小写匹配（bearer、BEARER、Bearer 均可用），并且会容忍多余空白。

2. ?api_key= URL 查询参数（备选）

https://mcp.pangolinfo.com/mcp?api_key=pgl_xxxxxxxx

最适合那些只能粘贴 URL 的客户端。如果你的密钥包含 URL 特殊字符，请对其做 URL 编码。当两种方式同时提供时，请求头（方式 1）优先。

客户端配置示例（Claude Code / Cursor —— "url" 风格的远程 MCP）

{
  "mcpServers": {
    "pangolinfo": {
      "url": "https://mcp.pangolinfo.com/mcp",
      "headers": { "Authorization": "Bearer pgl_xxxxxxxx" }
    }
  }
}

如果你的客户端无法设置请求头，请回退到 URL 形式： "url": "https://mcp.pangolinfo.com/mcp?api_key=pgl_xxxxxxxx"。

面向自定义 / 原生 HTTP 集成的说明

如果你直接调用该端点（而非通过标准 MCP 客户端）：

• 将 JSON-RPC 请求体以 POST 方式发送到 /mcp。
• MCP streamable 传输通常要求请求的 Accept 头同时声明 application/json 和 text/event-stream。本服务器会为你自动补齐缺失的媒体类型，因此简单的 Accept: application/json、Accept: */*，甚至完全不带 Accept 头均可正常工作 —— 你无需手动构造。
• 返回 401 表示密钥在请求头和查询字符串中均未找到 —— 请检查你的客户端是否确实发送了它（某些库在跨域重定向时会丢弃 Authorization 请求头）。

---

🧰 工具列表（18 款）

完整协作关系图（哪些工具串联调用哪些工具）请见 。

#	工具	用途	消耗（credits）
1	search_amazon	亚马逊关键词搜索 → 结构化商品列表	0.75
2	get_amazon_product	单个 ASIN 的 Listing 详情（标题 / 要点 / 特性 / aiReviewsSummary）	0.75
3	get_amazon_reviews	某 ASIN 的批量评论（VOC 挖掘）	0.75
4	list_bestsellers	按类目的亚马逊畅销榜	0.75
5	list_new_releases	按类目的亚马逊新品榜	0.75
6	list_seller_products	某个卖家名下的商品目录	0.75
7	list_category_products	某个类目叶子节点下的全部商品	0.75
8	search_categories	按关键词搜索亚马逊类目树	0.75
9	get_category_children	在类目树中向下钻取一层	0.75
10	filter_categories	按条件筛选类目节点	0.75
11	filter_niches	细分市场发现（规模 × 竞争 × 增长）	0.75
12	get_category_paths	解析某类目节点的完整祖先路径	0.75
13	search_local_maps	Google Maps 本地商家搜索	0.75
14	wipo_search	WIPO 全球外观设计 / 商标检索（知识产权清查）。设置 enableLitigation=true 可在同一次调用中一并关联相关的美国专利诉讼（PACER）案件	2（当 enableLitigation 命中专利时 +12）
15	ai_search	通过 Google SERP 进行 AI 搜索（AI Overview + 自然结果，附合规免责声明）	2
16	keyword_trends	通过 Google Trends 获取关键词趋势（附合规免责声明）	1.5
17	scrape_url	高级用户逃生通道：抓取任意亚马逊原始 URL + parserName（非标准页面）	0.75
18	search_amazon_alexa	亚马逊 Rufus AI 对话式商品推荐（基于场景，无需关键词）	6

外加一个免费的本地调用： pangolinfo_capabilities 会返回完整的工具目录、标准工作流和使用技巧，无需后端往返（0 credits）。它是一款自省辅助工具，并不属于这 18 款数据工具。

默认市场为 Amazon US（marketplaceId=ATVPDKIKX0DER，zip=90001）。可通过工具参数按次覆盖。

⏱️ 慢工具与客户端的工具调用超时

有两款工具因等待实时 AI 生成而确实耗时较长：

工具	典型延迟	最坏情况
search_amazon_alexa（Rufus）	每个 prompt 60–90 秒	多个 prompt 时 >200 秒
ai_search	约 30 秒	约 60 秒

大多数 MCP 客户端都会强制执行单次工具调用超时 —— 通常是 60 秒静默 —— 若超时内没有任何返回，就会中止调用。此时客户端会报告传输层超时/断连，而 agent 会误判为**"工具不可用/已损坏"**。这正是 search_amazon_alexa 常被标记为不可用的原因 —— 它总会稳定越过 60 秒静默红线。

以下两点可避免这种情况发生：

1. 服务器会发出进度心跳。 工具运行期间，服务器每 15 秒发送一次 notifications/progress —— 前提是你的客户端在调用中带上了 progressToken。符合规范的客户端会在每次心跳时重置空闲超时，因此整个 60–90 秒的渲染过程始终处于连接活跃状态。大多数现代 MCP 客户端会自动发送 progressToken —— 无需任何操作。

2. 对于不响应进度的客户端，请调高其超时。 如果你的客户端不支持 progressToken 或有硬性上限，请在使用 search_amazon_alexa 之前将其 MCP 工具调用超时上调至 ≥120 秒。设置位置取决于客户端（示例）：

   • Claude Code / 基于配置的客户端： 在客户端配置中调高 MCP 请求/工具超时。
   • 自定义 SDK 客户端： 在 callTool 请求选项中传入更大的 timeout（并且最好附带 progressToken）。

此外，建议每次 search_amazon_alexa 调用只用一个 prompt —— 多个 prompt 会线性叠加延迟，从而大大增加超时的可能性。

---

🔐 认证解析顺序

服务器按以下优先级解析 API Key：

1. CLI 参数：--api-key=pgl_xxx --api-base=... --scrape-base=...
2. 环境变量：PANGOLINFO_API_KEY、PANGOLINFO_API_BASE、PANGOLINFO_SCRAPE_BASE
3. 位于 ~/.pangolinfo/config.json 的配置文件：

   {
     "api_key": "pgl_xxxxxxxxxxxx",
     "api_base": "https://extapi.pangolinfo.com",
     "scrape_base": "https://scrapeapi.pangolinfo.com"
   }
   

4. 缺少密钥 → 启动失败，并给出可操作的错误提示。

CLI 参数优先于环境变量 —— 当你希望为不同服务器使用不同密钥、又不污染全局环境时非常方便。

---

🌐 国际化

工具描述和错误提示支持英文和中文。语言按以下顺序解析：--lang=zh|en → PANGOLINFO_LANG=zh|en → 操作系统区域设置（$LANG 以 zh* 开头 → 中文，否则英文）→ 完全无区域信号时默认为英文。因此中文区域设置的机器会自动获得中文；其他所有情况获得英文。如需强制指定语言：

"env": {
  "PANGOLINFO_API_KEY": "pgl_xxxxxxxx",
  "PANGOLINFO_LANG": "zh"
}

启动日志始终为英文（面向运维人员）；工具描述和错误 hint 字段则遵循解析后的区域设置。

---

✅ 验证安装

重启 AI 客户端后，向它提问：

列出所有可用的 pangolinfo MCP 工具。

你应该看到 18 款工具。然后试试：

使用 pangolinfo_capabilities，模式为 "summary"。

这是一次免费的本地调用 —— 如果它返回了工具目录，说明你的安装已正确接通。接下来，运行一个付费调用，例如：

在亚马逊搜索 "wireless mouse" 并返回前 5 个结果。

预期：扣除约 0.75 credits，返回约 300 KB 的结构化商品数据。

---

🛠️ 开发

npm install
npm run dev        # tsx src/server.ts — hot-reload
npm run build      # esbuild → dist/server.mjs
npm run typecheck  # tsc --noEmit
npm start          # node dist/server.mjs

项目结构

src/
├── server.ts           MCP stdio 入口 + 工具注册
├── auth.ts             API Key 解析（CLI > 环境变量 > 配置文件）
├── client.ts           HTTP 客户端（Authorization、User-Agent）
├── errors.ts           PangolinfoError + 状态码映射
├── config.ts           默认端点 / 常量
├── i18n.ts             zh/en 翻译查找
└── tools/
    ├── _types.ts             Tool / ToolContext 类型定义
    ├── index.ts              工具注册表（18 款工具 + capabilities）
    └── <verb_noun>.ts        每款工具一个文件

新增一款工具

1. 创建 src/tools/<verb_noun>.ts，导出一个 Tool 对象 —— 以 search_amazon.ts 为模板。
2. 在 src/tools/index.ts 中导入它并追加到 tools 数组。
3. Schema 使用 zod；为每个字段调用 .describe() —— AI 会读取这些描述。
4. 绝不要直接调用 fetch —— 请使用 ctx.client.post(...)。认证已自动注入。
5. 失败时抛出 PangolinfoError；HTTP 客户端在遇到非 2xx 响应时已自动抛出该错误。

---

🔒 安全与数据处理

我们高度重视运维人员和用户的安全。按设计，本 MCP 服务器：

• 携带你自己的密钥。 认证使用你个人的 PANGOLINFO_API_KEY（在 https://tool.pangolinfo.com/#/en/system/loading?sourceTag=github_amz 签发）。密钥从你本地的 AI 客户端配置或环境中读取 —— 除通过 TLS 1.2+ 发往 https://scrapeapi.pangolinfo.com（托管版本为 https://mcp.pangolinfo.com）外，绝不传输到任何其他地方。
• 无遥测。 本服务器不回传数据、不收集使用分析、不记录你的 prompt。唯一的对外流量是你通过工具显式调用的实际 Amazon / Google / WIPO 抓取 API 请求。
• 不收集个人身份信息（PII）。 本服务器不持久化任何用户账号信息、邮箱、IP 地理位置，也不保存 prompt 内容。工具调用仅转发你（或 AI agent）提供的参数。
• 只读。 每款工具都是严格只读的数据查询。它们都无法写入亚马逊、下订单、发表评论、修改 Listing，或对第三方平台执行任何有副作用的操作。
• 仅限 HTTPS 传输。 stdio 变体（本地）和托管变体（https://mcp.pangolinfo.com/mcp）均要求 HTTPS；HTTP 请求会被拒绝。
• 开源。 完整源码在本仓库中，采用 MIT 许可证 —— 任何人都可以审计服务器发送了什么、发送到哪里。
• 负责任使用。 Pangolinfo API 聚合的是公开的电商数据。你有责任确保对返回数据的使用符合底层平台（Amazon、Google 等）的服务条款以及你所在司法辖区的适用法律。

如发现安全问题，请私下报告至 security@pangolinfo.com —— 请不要为漏洞提交公开的 GitHub issue。

---

💬 支持

• API 文档：https://docs.pangolinfo.com
• 问题反馈：https://github.com/pangolinfo/pangolinfo-mcp/issues
• 电子邮件：support@pangolinfo.com

---

📄 许可证

MIT © Pangolinfo