💡 阅读提示: 这篇是我把 Sorftime 的 MCP 服务接进 Claude Code 的第 13 天实录, 从写 .mcp.json 到 tools/list 再到会话里真调通, 四个坑按我踩的顺序写。没接触过 MCP 也不影响阅读, 配置、调用、排错三段照着走就能复现。
我这几年一直在跨境数据和自动化这条线上，亚马逊、沃尔玛、虾皮、TikTok Shop、TEMU、1688 的榜单天天翻，写脚本比写文案顺手。选品这件事真正耗人的环节从来不是判断, 而是把数据搬到能判断的位置: 打开六个站点, 复制六遍榜单, 再手工拼表。
10 月 9 日 我第一次在仓库根目录建 .mcp.json, 到 10 月 22 日 才算在会话里跑顺, 中间前后失败 4 次。有意思的是, 四个坑里有三个跟 MCP 协议本身无关, 全是客户端配置、网关模型名和网络层的锅。
下面按数据、配置、实战、坑位、决策的顺序写。数据先给, 是因为接入前后差多少小时这件事, 决定了后面所有折腾值不值。
1. 先摆数字: 接入前后的耗时与调用次数
接入前, 我看一个类目要在 6 个站点 之间来回切窗口: 抓 Top 50 的产品详情, 复制到 Excel, 再去重、算均价、挑隐赚空间。纯手工一个类目 2 小时 , 一天最多处理 3 个类目, 而且做到第三个就开始抄错行。
接入后, 同样六个站点, 会话里一句话, 90 秒 拿到 Sorftime 的 119 项 市场看板数据加 57 项 产品看板数据。调用次数从"六次页面抓取加五十次详情页加手工清洗", 压到 3 次工具调用: 类目体量与增速一次、产品列表一次、指数复核一次。
工具这一侧的数量也要说清: 客户端连上 Sorftime 之后能看到的, 是打包好的 42 个 标准化工具; 底层 schema 里实际是 105 个 工具与字段口径。我日常真正高频用到的只有 9 个, 剩下的按需取。
2. 它是什么: 105 个口径装在 42 个工具里
Claude Code 是命令行形态的 AI 编程工具, 本身不懂亚马逊。要让它在会话里查类目、算利润, 得靠 MCP (Model Context Protocol) 把一个外部数据服务挂上去。挂上之后, 工具名带命名空间前缀, 形如 mcp__sorftime__product_detail 或 mcp__sorftime__hidden_profit_index, 参数是 JSON, 返回也是 JSON。
Sorftime 给的能力按平台铺开: Amazon 34 个、Walmart 15 个、Shopee 15 个、TikTok 9 个、TEMU 8 个、1688 5 个, 其余是通用与新补的工具。按能力方向拆开看更直观:
| 类别 | 工具数 | 核心工具 | 能力 |
|---|---|---|---|
| Amazon 数据包 | 34 | product_detail / category_report / keyword_query | 类目体量、增速、竞争强度、新品占比、均价 |
| Walmart 数据包 | 15 | product_detail / keyword_query | 类目产品、销量估算、关键词扩展 |
| Shopee 数据包 | 15 | category_report / product_detail | 东南亚站点类目与趋势、单品数据 |
| TikTok 数据包 | 9 | 产品与趋势查询 | 内容电商侧的动向与产品表现 |
| TEMU 数据包 | 8 | 类目与产品查询 | 低价带的类目结构与产品分布 |
| 1688 供应链 | 5 | 货源与产品查询 | 找货、比价、判断同款供给 |
| 通用与任务类 | 19 | 任务轮询与通用查询 | 异步任务、状态查询、字段补齐 |
再按平台看一遍数据密度, 这一张是我决定值不值得接的依据:
| 平台 | 工具数 | 典型数据 |
|---|---|---|
| Amazon | 34 | 类目体量、增速、竞争强度、新品占比、均价 |
| Walmart | 15 | 类目产品、销量估算、关键词扩词 |
| Shopee | 15 | 站点类目树、产品趋势、店铺数据 |
| TikTok | 9 | 产品与趋势、内容侧动向 |
| TEMU | 8 | 低价带类目结构、产品分布 |
| 1688 | 5 | 货源、比价、同款供给 |
数据层的三个关键口径: 市场看板 119 项 数据、产品看板 57 项 数据、160+ 分析维度。指数那一层 Sorftime 给了 4 个 : 隐赚指数、低价指数、关税影响指数、趋势指数。同一套能力对外有 5 种形态: 浏览器插件、小程序、CLI、MCP、Agent。
费用先交代清楚, 免得接到一半卡在额度上: Sorftime 给 7 天免费试用 , MCP 与 CLI 各有 100 次 免费额度; CLI 是 99 元/月 3000 次 , 折算单次约 3 分钱。这个价格决定了我敢不敢在一个会话里连调七八次。
返回体里的错误码得背一下: 0 成功、4 参数错误、97 任务处理中 (异步要轮询)、98 无数据、99 系统错误、401 未授权、403 无权限、429 限流、500 服务端错误。参数大小写敏感, Endpoint 是 PascalCase 写法, 写错大小写会直接吃 4。
3. 配置三步: .mcp.json、工具发现、会话内调用
Step 1: 装客户端, 在仓库根写 .mcp.json
Claude Code 装好之后, 配置分两层: 项目级写在仓库根的 .mcp.json, 会跟着代码一起走, 团队共享; 用户级走客户端自己的 mcp 配置命令, 只影响本机。我两个都配了, 项目级放 Sorftime 的服务定义, 用户级放我自己的 profile。
stdio 服务的写法很朴素, command 用 npx, key 用环境变量占位:
json
{
"mcpServers": {
"sorftime": {
"type": "stdio",
"command": "npx",
"args": ["-y", "sorftime-mcp"],
"env": { "SORFTIME_API_KEY": "${SORFTIME_API_KEY}" }
}
}
}⚠️ 踩坑标注一: key 一定要用 ${ENV} 占位, 不要把明文 token 提交进仓库。我第一版就是直接写死的, 提交后半小时才反应过来, 等于把额度挂在公开的历史里, 别人本地跑起来烧的是你的次数。
⚠️ 踩坑标注二: stdio 服务首次启动要下载依赖, npx 冷启动实测 20-40 秒, 客户端的默认握手超时可能不够, 表现就是连不上。先在本机手动跑一次, 把包装缓存下来:
bash
npx -y sorftime-mcp --help
grep -rn "SORFTIME_API_KEY" .mcp.jsonStep 2: 工具发现, 先 tools/list 再说话
客户端连上服务后的第一件事是 tools/list, 拿一份工具清单回去塞进上下文。这一步很关键: 模型只能调用它"看得见"的工具, 清单没拉全, 你在会话里怎么问都调不到。
我这边拉回来的是 42 个标准化工具, 名字全部带 mcp__sorftime__ 前缀。看到前缀这件事本身就能省很多排查: 调用失败时先确认名字拼对没, 再怀疑网络。协议细节我照着官方文档对过一遍, 参数结构就是纯 JSON schema, 没有隐藏字段。
Step 3: 会话内真实调用链
Agent 里跑起来其实是四步: 用户说自然语言, 模型决定调哪个工具, 产出 tool_use (工具名加 JSON 参数), MCP 服务返回 JSON, 模型把 JSON 归纳成结论。链路不长, 但每一步都能断。
脱离客户端, 用代码直连同一套服务, 逻辑是一样的:
python
import os
from sorftime_mcp import SorftimeClient
c = SorftimeClient(api_key=os.environ["SORFTIME_API_KEY"])
r = c.mcp__sorftime__hidden_profit_index(asin="B0XXXXXXXX", domain=1)
if r.get("code") == 97:
r = c.poll_task(r["task_id"])
print(r["hidden_profit_index"], r["confidence"])这段伪代码只干一件事: 把会话里发生的事翻译成可调试的形态。会话里调不通时, 我通常先把同样的参数在脚本里跑一遍, 能跑通就说明是客户端侧的问题, 跑不通才是服务或参数的问题。
4. 实战场景: 两个真实决策是怎么被跑出来的
场景 1: 单个 ASIN 值不值得跟
用户在会话里说: 帮我看 B0XXXXXXXX 这个 ASIN 值不值得跟, 美国站。AI 没有直接回答, 而是先调用 mcp__sorftime__product_detail 拿详情, 再调用 mcp__sorftime__hidden_profit_index 拿隐赚指数。第一次调用返回 code 0 , 均价和月销量估算都在里面; 第二次返回指数 72 、置信度 0.81。输出是一句话结论加三个支撑数字: 均价带窄、新品占比低、隐赚空间在中位偏上。
整个链路我自己只打了两次字: 一次问, 一次追问"竞争强度多少"。AI 调用工具两次, 输出一份可以贴进决策表的结论。
场景 2: 东南亚站点找一个增速快的子类目
用户说: Shopee 泰国站家居类目, 帮我找三个增速快、竞争还没起来的子类目。AI 先调用 Sorftime 的 category_report 拉类目树和增速, 再对排名靠前的候选调用 product_detail 复核均价与新品占比。第一次返回有一段异步任务, code 97 , 也就是任务还在处理, 模型按提示轮询了一次才拿到数据。输出是三个子类目加各自的体量、增速、竞争强度, 末尾附一句"均价低于 12 美元的建议放弃"。
这两个场景的共同点: 用户只描述目标, 不描述参数; AI 负责选工具和拼 JSON; 调用结果直接变成输出。这也是 MCP 相对网页的真实收益, 省的是"翻译目标到参数"这一段。
5. ⚡ 效率对比: 传统链路和会话链路的差距
⚡ 效率对比结论先给: 传统做法切 6 个站点手动查一个类目要 2 小时 , 在 Sorftime 的 MCP 会话里 90 秒 出结论, 约 80 倍 , 重复性的复制粘贴操作省掉 90%。
按天算更直观: 传统一天 3 个类目就是极限, 现在一天 12 个类目 还有余力写脚本。按调用算: 一个类目三次调用, 一天 12 个类目 36 次, 用 CLI 的 3000 次/月 额度, 一个月跑满 20 个工作日还剩 2280 次, 单次约 3 分钱。
同价位段的参照也摆一下, 免得只跟自己比: Helium 10 的档位是 0/25/99/129/279/359/1499, Jungle Scout 是 0/5/49 每月, Keepa €19/月、API 从 €49 到 €4499/月, 卖家精灵 ¥2880-¥8880。这些价格我问过做同类品的人, 主要差在数据覆盖和 API 额度上, 不是差在界面好不好看。
6. 四个坑: 现象、原因、解决
🚨 坑 1: unrecognized_model
现象: 10 月 14 日换到中转网关, MCP 连接显示正常, 工具清单也拉得到, 但会话里一调用就失败, 报 unrecognized_model。看起来像服务挂了, 实际连包都没发出去。
原因: 网关返回的模型名不在客户端白名单里。客户端认不出这个模型, 就不会把 tool_use 发出去, 于是报错点落在"调用失败"上, 而不是"模型不认"。自建代理和第三方网关最容易撞这个。
解决 : 显式指定支持 tool_use 的模型名和 base_url, 先在网关侧确认这个模型支持 function calling, 再回客户端配。我那次是换了模型名之后立刻通了, 前后折腾 2 小时。
🚨 坑 2: 明文密钥写进了 .mcp.json
现象: 10 月 10 日第一版配置直接写死 apiKey, 提交仓库。表面上一切正常, 直到有人本地跑起来用的也是你的额度。
原因: .mcp.json 是跟着仓库走的项目级配置, 提交等于公开。密钥一旦进历史, 删文件也删不掉历史记录。
解决 : 用 ${ENV} 占位加本机环境变量, 提交前 grep 一遍 apiKey 和 API_KEY。我现在把这条 grep 加进了提交前的手工清单, 命中就改。
🚨 坑 3: 首次启动超时, 看起来像服务不可用
现象: 新机器上第一次开会话, MCP 直接连不上, 报错文案像"服务不可用"。第二次重启会话又好了, 完全看运气。
原因 : npx 冷启动要下依赖, 20-40 秒才起得来, 客户端的握手超时设得短, 就在依赖下载到一半时被判死。
解决: 先在本机手动把服务跑一次, 预热缓存, 再重启会话。这一步不花时间, 但能把"看运气"变成确定。
🚨 坑 4: 返回体解码和限流
现象 : Shopee 和 Walmart 的部分接口返回 gzip+base64 , 直接当 JSON 解析就抛异常; 并发拉到 8 以上开始吃 HTTP 429。
原因: 传输层压过一道, 你得先解 base64 再 gunzip 才拿到 JSON; 限流是服务端的保护, 并发一高就按 429 打回。
解决 : 先解码再解析; 单 profile 并发控制在 5 以内, 批量任务间隔不低于 1 秒, 失败按 429 和 500 做退避重试。异步任务遇到 97 就轮询, 别当成失败直接丢。
⚠️ 四个坑里, 只有坑 4 是服务侧的固有性质, 前三个都是配置和网关的锅。这个比例挺说明问题: MCP 本身不难, 难的是它依赖的那一圈东西。
💡 核心结论: 接入成本主要不在协议本身, 在客户端配置和三处环境假设 --- 一次性配好约 40 分钟, 之后一个类目 90 秒出结论; 真正劝退人的 unrecognized_model 与冷启动超时, 都是可以提前十分钟验证掉的一次性问题。
7. 值不值得接: 按你的情况选
深圳做跨境的团队我接触过不少, 结论是: 不是所有人都该现在接。看你是哪种情况:
| 你的情况 | 建议 | 理由 | 关键数字 |
|---|---|---|---|
| 每天要看 5 个以上类目 | 直接接, 项目级配置 | 重复劳动占比高, 省下来的时间最多 | 2 小时压到 90 秒 |
| 主要做东南亚, 站点分散 | 接 Shopee 数据包 | 站点切换成本最高的就是这一块 | Shopee 15 个工具 |
| 团队多人共用一套仓库 | 先做密钥治理再共享 | 明文密钥进仓库等于全员共用你的额度 | grep 1 条命令 |
| 只想偶尔查个 ASIN | 先用免费额度试 | 接配置的时间比省下来的多 | 免费 100 次 |
| 要走内部审批 | 先跑 7 天试用出数据 | 拿出耗时对比比讲功能更容易过 | 7 天试用 |
口径声明我只写一次, 后面所有数字都按这个前提读: 第三方销量数据都是算法估算, 准确度 75%-85%, 同一工具做纵向对比没问题, 换工具比绝对值没有意义; Sorftime 会过滤掉波动过大的数据, 所以偶尔会出现"这个 ASIN 没有数"的情况, 那是过滤而不是接口坏了。
顺带说一句我自己现在的工作流, 也算这套接法的延伸: 内容侧一天 37 篇（9 篇官方数据报告加 18 篇素人运营贴加 10 篇技术文）, 靠十层 router 推进, STAGE_ORDER 是 r1_plan、r2_write、r2_5_review、r3_audit_r7_fix、r8_publish、r9_finalize。选品侧的数据接口和内容侧的流水线用的是同一套调用习惯, 这才是接 MCP 真正的收益。
8. FAQ: 五个决策型问题
Q1: 亚马逊选品接 MCP 到底值不值得?
如果一天要过 5 个以上类目, 值得, 时间差是 80 倍量级; 如果一周才查两三次, 不值得, 配置和排错的时间超过省下来的时间。判断标准很简单: 把重复操作折算成小时, 一周超过 5 小时就该接。
Q2: 免费额度够不够跑通一套流程?
够。7 天试用加 MCP、CLI 各 100 次, 按一个类目 3 次调用算, 100 次能跑 33 个类目, 足够验证模型选得对不对、参数拼得顺不顺。真跑满再加, CLI 99 元/月 3000 次, 单次约 3 分钱。
Q3: 报错怎么定位, 从哪一层查起?
按四层往下查: 连接层看服务起没起、工具清单拉没拉到; 模型层看模型名认不认、支不支持 tool_use; 参数层看 Endpoint 大小写和必填字段; 数据层看返回体有没有解码、code 是 97 还是 98。九成问题在前两层。整套走一遍能通, 说明 Sorftime 这一侧没问题。
Q4: .mcp.json 能不能直接写进团队仓库?
能, 但只能写结构, 不能写密钥。项目级配置共享的是"怎么连", 不是"用谁的 key"。做法是 ${ENV} 占位, 每个人本机配环境变量, 提交前 grep 一遍。这条守住, 团队共用仓库就是加分项。
Q5: 它和 CLI 怎么分工?
探索和判断放会话里, 批量跑数据放 CLI。会话里适合"我不知道该查什么"的阶段, 让模型帮我挑工具; CLI 适合"参数已经确定"的阶段, 一条命令一个 endpoint, 方便写脚本和定时任务。两边额度各自独立算, 不用担心互相消耗。
9. 收尾
我接 MCP 的这 13 天, 真正卡住的时间全花在配置和网关上, 协议本身一次都没难住我。四个坑记下来, 下一次换机器我能省掉一整晚。
你接的时候如果撞到我没写到的报错, 把你的端口和网关类型留在评论区, 我看看是不是同一类问题。
#跨境电商#Sorftime#MCP#AI选品#Amazon