MCP 文档 #
本文档说明如何将 有数-MCP(标准名 youshu-mcp)接入到支持 MCP 的客户端中。该服务基于
MCP over HTTP(Streamable HTTP) 协议,提供有数广告素材检索、品牌 / 店铺 / 达人 ID 反查、
店铺与商品销售指标查询等 11 个工具(V1),全部通过标准 JSON-RPC 2.0 调用。
1连接信息#
| 项目 | 值 |
|---|---|
| 服务名(标准) | youshu-mcp,配置文件中 mcpServers 的键名 |
| 端点 URL | https://api.youshu.youcloud.com/mcp |
| 协议 | MCP over HTTP(Streamable HTTP),JSON-RPC 2.0 |
| 认证 | Authorization: Bearer <api-key> |
| API Key | 由有数服务方提供,接入时替换 <api-key>获取 API Key |
| 请求头 | Content-Type: application/json + Accept: application/json, text/event-stream |
配置示例#
标准 MCP 客户端配置(mcpServers):
{
"mcpServers": {
"youshu-mcp": {
"url": "https://api.youshu.youcloud.com/mcp",
"headers": {
"Authorization": "Bearer <api-key>"
}
}
}
}把下面这段话整段发给你的 Agent(先将 <api-key> 替换为服务方提供的值),由它写入对应客户端的配置文件并完成安装:
请帮我安装以下 MCP:
{
"mcpServers": {
"youshu-mcp": {
"url": "https://api.youshu.youcloud.com/mcp",
"headers": {
"Authorization": "Bearer <api-key>"
}
}
}
}2工具速览(11 个)#
服务共提供 11 个工具(V1),按用途划分为四类。建议的调用链路:filterOptions 取枚举 → searchBrands / searchShops / searchKols 反查 ID → searchMaterials 检索素材 → materialCreativeList / creativeAIAnalysisData / creativeAsr 下钻;商品与店铺线走 productSalesRanking → shopSalesMetrics。
creativeAIAnalysisData 仅 策略 pro 版 / 至尊版 开放,其余 10 个工具策略版起即可用。逐工具权限见下表。| 工具 | 作用 | 扣点 | 策略版 | 策略 pro 版 | 至尊版 |
|---|---|---|---|---|---|
| searchMaterials | 主素材搜索:按关键词 / 品牌 / 店铺 / 达人 / 品类 / 时间(最大 180 天)等维度检索广告素材 | 100/条 | ✓ | ✓ | ✓ |
| filterOptions | 一次拉全部筛选项候选值(品类、素材类型、视频时长、素材比例等) | 100/次 | ✓ | ✓ | ✓ |
| searchBrands | 按品牌名搜品牌 ID(供 searchMaterials 的 brandId) | 100/次 | ✓ | ✓ | ✓ |
| searchShops | 按店铺名搜店铺 ID(供 shopId 筛选) | 100/次 | ✓ | ✓ | ✓ |
| searchKols | 按达人关键词搜 UID(media 固定 20=抖音) | 100/次 | ✓ | ✓ | ✓ |
| kolBaseInfo | 达人基本信息(UID、昵称、粉丝数、关联店铺),入参 ccUid | 100/次 | ✓ | ✓ | ✓ |
| shopSalesMetrics | 店铺级真实交易指标,仅四项:直播销售额 live_sales、直播销量 live_solds、新增销量 solds、新增销售额 sales(禁推导客单价) | 100/次 | ✓ | ✓ | ✓ |
| productSalesRanking | 商品销售总榜-抖店:时间范围 + 商品关键词,按新增 / 累计销量排序 | 100/条 | ✓ | ✓ | ✓ |
| materialCreativeList | 按素材 ID 查关联广告(文案、流量平台、投放日期 / 天数、广告 ID) | 100/次 | ✓ | ✓ | ✓ |
| creativeAIAnalysisData | 素材 ID 查卖点标签与自然语言理解内容(画面 / 台词提取的商品特点、功效等) | 400/条 | ✕ | ✓ | ✓ |
| creativeAsr | 按素材 ID 批量获取口播文案(asr 旁白) | 100/条 | ✓ | ✓ | ✓ |
searchMaterials、productSalesRanking、creativeAsr 按返回条数扣点(100/条),creativeAIAnalysisData 为 400/条。按条计费的工具在翻页拉全量前,先估算总条数。每次请求都会做相对应的扣点,调用 MCP 前严格完整阅读文档,调用时严格根据 MCP 说明请求和入参,并合理规划请求路径,避免乱尝试导致点数浪费。
筛选枚举#
素材搜索的前置依赖,同一次对话调用一次后复用。
| 工具 | 用途 | 扣点 |
|---|---|---|
| filterOptions | 一次拉取全部筛选项候选值(品类、素材类型、视频时长、素材比例、素材标签、受众人群等)。无入参,一次调用即返回全部 label,返回的是筛选常量集合;返回体较大,建议落盘后按 label 取用。 无入参 | 100/次 |
ID 检索(前置)#
品牌 / 店铺 / 达人名称 → ID 的反查入口,产出的 ID 供 searchMaterials 精确定向。
| 工具 | 用途 | 扣点 |
|---|---|---|
| searchBrands | 按品牌名搜品牌 ID(返回候选品牌 ID、名称与可用别名 / 介绍),供 searchMaterials 的 brandId。 | 100/次 |
| searchShops | 按店铺名搜店铺 ID(返回候选店铺 ID 与名称,同名店铺须逐一辨认),供 shopId 筛选;店铺来源可限定抖音 / 快手 / 度小店,默认抖音。 | 100/次 |
| searchKols 仅抖音 | 按达人关键词搜 UID(返回候选 UID 与昵称,同名账号不能仅凭昵称判定身份),供 uid 筛选;media 固定传 20(抖音)。 | 100/次 |
素材与创意(核心)#
| 工具 | 用途 | 扣点 |
|---|---|---|
| searchMaterials 主力 | 主素材搜索:按关键词 / 品牌 / 店铺 / 达人 / 品类 / 时间(最大 180 天)等维度检索广告素材,返回素材内容、曝光 / 关联指标和分页信息;不提供单品销量或达人粉丝量。 | 100/条 |
| materialCreativeList | 按素材 ID 查关联广告列表,返回广告文案、流量平台、设备类型、投放日期、投放天数和广告 ID。 | 100/次 |
| creativeAIAnalysisData | 批量获取素材的创意卖点、AI 解读(从画面或台词提取的商品特点、功效等标签),一次最多 100 条;仅策略 pro 版、至尊版可用。 | 400/条 |
| creativeAsr | 按素材 ID 批量获取广告视频已提取的口播文案(asr 旁白),一次最多 100 条;无效素材 ID 不返回。 | 100/条 |
达人 · 店铺 · 商品#
| 工具 | 用途 | 扣点 |
|---|---|---|
| kolBaseInfo | 达人基本信息:UID、昵称、粉丝数、关联店铺;入参 ccUid 来自 searchKols 返回或素材里的 cc_uids。 | 100/次 |
| shopSalesMetrics | 店铺级真实交易指标,仅返回直播销售额、直播销量、新增销量、新增销售额四项;不得推导客单价或补充其他销售指标。 | 100/次 |
| productSalesRanking | 商品销售总榜-抖店:按统计时间范围 + 商品关键词筛选,支持按新增 / 累计销量、销售额、评论数、好评率等排序,返回商品 ID、名称、所属店铺、价格、新增销量和累计销量。 | 100/条 |
3工具参数详解#
3.1 filterOptions(先调一次)#
无入参。返回体按 label 分组,searchMaterials 各枚举入参的取值均来自对应 label:
| label(入参) | 用途 |
|---|---|
| category | 品类;完整 ID 列表由套餐决定 |
| mtype | 素材类型(视频 / 图片等) |
| videoTime | 视频时长 |
| ratios | 素材比例 |
materialTag(materialTagIds) | 素材内容类型标签 |
| targetingAudience | 受众人群标签 |
| promotionMaterialType | 推广类型 |
| shopType | 店铺类型 |
| accountType | 账号类型:all 所有 / shop 店铺账号 / auth 授权账号 / kol 达人账号 / enterprise 企业账号 |
店铺来源 site_id_lst 与达人媒体 media 的枚举不在 filterOptions 返回内,直接使用固定值(见 3.3)。
3.2 searchMaterials(素材搜索主力)#
必填:page、order
排序枚举(order):
| 枚举值 | 含义 |
|---|---|
max_dt_desc | 投放最新时间降序(默认) |
material_score_desc | 素材质量指数降序 |
cnt_ad_id_desc | 关联广告数降序 |
cnt_dt_desc / cnt_dt_asc | 投放时长降 / 升序 |
cnt_product_desc / cnt_product_asc | 关联商品数降 / 升序 |
cnt_live_id_desc / cnt_live_id_asc | 关联直播数降 / 升序 |
impression_inc_2y_desc | 总曝光降序 |
cnt_uid_desc | 关联达人数降序 |
cnt_product_sm_desc / cnt_product_cid_desc / cnt_product_card_desc | 关联带货商品 / CID 商品 / 商品卡商品数降序 |
view_count_desc / like_count_desc | 播放数 / 点赞数降序 |
_score_desc | 关键词相关性降序 —— 仅带 keyword 时可用 |
常用筛选
| 参数 | 类型 | 说明 |
|---|---|---|
keyword | string | 关键词检索 |
searchField | 枚举 | 关键词命中字段,默认 all:all / asr / slogan / brand_name / talent_name / product_title / shop_name / seller_company_name / video_title / video_asr |
brandId / shopId / uid | ID | 定向品牌 / 店铺 / 达人素材;ID 来自 searchBrands / searchShops / searchKols(见 3.3) |
startDate / endDate | string | YYYY-MM-DD,时间窗最大 180 天 |
category / mtype / videoTime / ratios / materialTagIds / targetingAudience / promotionMaterialType / shopType | 枚举 ID | 取值来自 filterOptions 对应 label(见 3.1) |
accountType | 数组 | 账号类型:all / shop / auth / kol / enterprise |
special | 枚举 | 仅 "NP":新投放素材(第一次出现且之前未出现过) |
resolution | 枚举 | 高清素材:是传 "1,2",否不传 |
is_aigc / isSearchAiScene | int | AI 视频 / 搜画面:是传 1,否不传 |
isExact | boolean | 精准搜索,配合关键词使用 |
material_score_gte / material_score_lte | int | 素材质量指数 ≥ / ≤ 阈值 |
searchDsl | 数组 | 高级检索,每项 {id, key, type, value}:key 含 product_title / shop_name / kol_name / campaign_name / slogan / asr / audience_words / video_title / video_asr;type 含 include / exclude / equal / notEqual |
startDate 与 endDate 的跨度最大 180 天;更长周期请拆成多次调用。该工具按返回条数扣点(100/条),翻页前先估算总量。3.3 ID 检索工具#
searchBrands
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 是 | 品牌关键词 |
page | integer | 是 | 页码 |
searchShops
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 否 | 店铺关键词 |
site_id_lst | 枚举 | 否 | 店铺来源:10502 抖音(默认)/ 20902 快手 / 11001 度小店 |
page | integer | 否 | 页码 |
searchKols
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
media | 枚举 | 是 | 媒体平台,当前仅支持 20(抖音) |
keyword | string | 否 | 抖音号关键词 |
page | integer | 否 | 页码 |
三个工具的 page 必填性不一致(searchBrands 必填,另两个可选),统一从 1 传起最稳。
3.4 达人 / 店铺 / 商品工具#
kolBaseInfo
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
ccUid | string | 是 | 达人 UID,来自 searchKols 返回的 uid 或素材里的 cc_uids |
shopSalesMetrics
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
shop_ids | string | 是 | 店铺 ID,多个用英文逗号分隔(如 "123,456"),来自 searchShops |
startDate / endDate | string | 是 | 统计日期区间,YYYY-MM-DD |
site | 枚举 | 否 | 平台站点标识;schema 未给出枚举值,需要时咨询服务方 |
live_sales / live_solds / solds / sales 回答;不要推导客单价或补充其他销售指标;空数据 / 报错时明确说明,不得用广告素材数据替代或编造。productSalesRanking
必填:sort、page
排序枚举(sort):
| 枚举值 | 含义 |
|---|---|
measure | 选品指数 / 24h 新增销量 |
qs_incr_1h / qs_incr_3h / qs_incr_6h / qs_incr_12h / qs_incr_24h | 近 N 小时新增销量降序 |
qs_incr_xday / qs_incr_amount_xday | 近 x 天新增销量 / 新增销售额降序(x 的指定方式 schema 未给出,慎用) |
qs_total / qs_total_amount | 累计销量 / 累计销售额降序 |
qs_incr_amount_day | 按新增销售额降序 |
comment_count / applause_rate | 评论数 / 好评率降序 |
first_monitor_time / trend | 首次发现时间 / 趋势指数降序 |
常用筛选
| 参数 | 类型 | 说明 |
|---|---|---|
keyword | string | 商品关键词 |
startDate / endDate | string | 统计时间范围,YYYY-MM-DD |
unitId / product_id_lst | ID / 数组 | 单品 ID / 商品 ID 列表 |
shopId / company_id | ID | 店铺 ID(来自 searchShops)/ 商家 ID |
site_id / category / promotionType / shopType | 枚举 ID | 渠道 / 品类 / 推广方式 / 店铺类型 |
hasBrand | int | 店铺品牌标识:1 有 / 0 无 |
isNew / isExact | boolean | 新上榜 / 精准搜索 |
sloganDigest | ID | 文案 ID |
区间筛选(成对的 min / max 参数)
| 参数组 | 说明 |
|---|---|
min_price / max_price | 价格区间 |
min_qs_incr_24h / max_qs_incr_24h | 24h 新增销量区间(另有 12h、6h 同名组) |
min_qs_total / max_qs_total | 累计销量区间 |
min_qs_total_amount / max_qs_total_amount | 累计销售额区间 |
min_qs_incr_day / max_qs_incr_day | 新增销量区间(按日) |
min_qs_incr_amount_day / max_qs_incr_amount_day | 新增销售额区间(按日) |
min_comment_count / max_comment_count | 评论数区间 |
min_applause_rate / max_applause_rate | 好评率区间 |
min_measure / max_measure | 选品指数区间 |
trend | 趋势指数范围,逗号分割:min_trend,max_trend |
startMonitor / endMonitor | 商品首次发现时间最小 / 最大值 |
3.5 素材级工具#
materialCreativeList
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
materialId | string | 是 | 素材 ID,来自 searchMaterials |
page | integer | 是 | 页码 |
startDate / endDate | string | 否 | 投放时间范围,YYYY-MM-DD |
sort | 枚举 | 否 | max_dt_desc / max_dt_asc(投放时间降 / 升序)/ duration_desc / duration_asc(投放时长降 / 升序) |
creativeAIAnalysisData(仅策略 pro 版 / 至尊版)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
materialIds | 数组 | 是 | 素材 ID 数组,一次最多 100 条,超出部分被丢弃;建议收集齐后批量传入 |
creativeAsr
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
materialIds | 数组 | 是 | 素材 ID 数组,一次最多 100 条;返回广告视频已提取的口播 / 旁白文案,无效素材 ID 不返回 |
3.6 返回字段要点#
| 工具 | 返回要点 |
|---|---|
searchMaterials | 素材内容 + 曝光 / 关联指标 + 分页信息;素材含有效 cc_uids 时可传给 kolBaseInfo 查达人信息 |
shopSalesMetrics | live_sales 直播销售额 · live_solds 直播销量 · solds 新增销量 · sales 新增销售额(仅此四项) |
productSalesRanking | 商品 ID、商品名称、所属店铺、价格、新增销量、累计销量 |
materialCreativeList | 广告文案、流量平台、设备类型、投放日期、投放天数、广告 ID |
creativeAIAnalysisData | id(与入参一一对应)、sellPoint(创意卖点)等内容信息;部分素材可能暂无解读内容 |
creativeAsr | id 与口播文案(asr 旁白);无效素材 ID 不返回 |
searchBrands / searchShops / searchKols | 候选 ID + 名称列表(品牌另含别名 / 介绍;达人另含昵称) |
4返回数据与截断的解决方案#
解决思路(可把这段描述交给 Agent,由它自行生成脚本,无需手写):
data: 前缀行的 JSON)。直连拿到的是服务端完整响应,不受客户端截断保护影响。page 参数从 1 开始依次翻页,直到取满总量或某页返回条数小于页大小。./mcp_dumps/search_p1.json),数据不经过终端、不进入 Agent 上下文。CERTIFICATE_VERIFY_FAILED(证书链校验失败),安装 certifi(pip3 install certifi)并指定其证书即可。5常见问题与注意事项#
| # | 场景 | 建议做法 |
|---|---|---|
| 1 | 哪些套餐可用 | 旗舰版 / 旗舰 pro 版 / 尊享版均不可用;策略版 / 策略 pro 版 / 至尊版可用,其中 creativeAIAnalysisData 仅策略 pro 版 / 至尊版开放,其余 10 个工具策略版起可用(明细见第 2 节权限表) |
| 2 | 扣点怎么算 | 多数工具 100/次;searchMaterials、productSalesRanking、creativeAsr 按返回条数 100/条,creativeAIAnalysisData 400/条 —— 按条计费可根据 total 的总量合理规划,减少不必要的点数耗费 |
| 3 | 策略版调用 creativeAIAnalysisData 无权限 | 该工具仅策略 pro 版 / 至尊版开放,策略版不可用;素材口播文案可改用 creativeAsr(策略版起可用);如返回内容和权限不匹配,可咨询有米有数服务人员 |
| 4 | 想搜指定品牌 / 店铺 / 达人的素材 | 先 searchBrands / searchShops / searchKols 拿 ID,再传 brandId / shopId / uid,不要用 keyword 硬搜名称 |
| 5 | 店铺销售额 / 销量怎么答 | shopSalesMetrics 仅返回 live_sales / live_solds / solds / sales 四项;不要推导客单价、不补充其他指标、不用素材数据替代(见 3.4) |
| 6 | searchKols 请求需要限定 media | media 为必填且当前仅支持 20(抖音),调用时固定传 20 |
| 7 | 时间范围超过 180 天 | searchMaterials 时间窗最大 180 天,更长周期拆成多次调用 |
| 8 | 拉全量素材 / 商品榜 | 单页条数固定且按条扣点,请采用「脚本直连 + 逐页落盘」,终端只回传摘要(见第 4 节) |