MCP 文档

MCP 文档 #

本文档说明如何将 有数-MCP(标准名 youshu-mcp)接入到支持 MCP 的客户端中。该服务基于 MCP over HTTP(Streamable HTTP) 协议,提供有数广告素材检索、品牌 / 店铺 / 达人 ID 反查、 店铺与商品销售指标查询等 11 个工具(V1),全部通过标准 JSON-RPC 2.0 调用。

1连接信息#

项目值
服务名(标准)youshu-mcp,配置文件中 mcpServers 的键名
端点 URLhttps://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):

json
{
  "mcpServers": {
    "youshu-mcp": {
      "url": "https://api.youshu.youcloud.com/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

把下面这段话整段发给你的 Agent(先将 <api-key> 替换为服务方提供的值),由它写入对应客户端的配置文件并完成安装:

text 发送给 Agent 的提示词
请帮我安装以下 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。

套餐可用性 旗舰版 / 旗舰 pro 版 / 尊享版 均不可用本服务;策略版 / 策略 pro 版 / 至尊版 可用,其中 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、昵称、粉丝数、关联店铺),入参 ccUid100/次✓✓✓
shopSalesMetrics店铺级真实交易指标,仅四项:直播销售额 live_sales、直播销量 live_solds、新增销量 solds、新增销售额 sales(禁推导客单价)100/次✓✓✓
productSalesRanking商品销售总榜-抖店:时间范围 + 商品关键词,按新增 / 累计销量排序100/条✓✓✓
materialCreativeList按素材 ID 查关联广告(文案、流量平台、投放日期 / 天数、广告 ID)100/次✓✓✓
creativeAIAnalysisData素材 ID 查卖点标签与自然语言理解内容(画面 / 台词提取的商品特点、功效等)400/条✕✓✓
creativeAsr按素材 ID 批量获取口播文案(asr 旁白)100/条✓✓✓
扣点计费提醒 多数工具按每次调用扣点(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)。

必填: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 时可用

常用筛选

参数类型说明
keywordstring关键词检索
searchField枚举关键词命中字段,默认 all:all / asr / slogan / brand_name / talent_name / product_title / shop_name / seller_company_name / video_title / video_asr
brandId / shopId / uidID定向品牌 / 店铺 / 达人素材;ID 来自 searchBrands / searchShops / searchKols(见 3.3)
startDate / endDatestringYYYY-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 / isSearchAiSceneintAI 视频 / 搜画面:是传 1,否不传
isExactboolean精准搜索,配合关键词使用
material_score_gte / material_score_lteint素材质量指数 ≥ / ≤ 阈值
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
时间窗上限 180 天 startDate 与 endDate 的跨度最大 180 天;更长周期请拆成多次调用。该工具按返回条数扣点(100/条),翻页前先估算总量。

3.3  ID 检索工具#

searchBrands

参数类型必填说明
keywordstring是品牌关键词
pageinteger是页码

searchShops

参数类型必填说明
keywordstring否店铺关键词
site_id_lst枚举否店铺来源:10502 抖音(默认)/ 20902 快手 / 11001 度小店
pageinteger否页码

searchKols

参数类型必填说明
media枚举是媒体平台,当前仅支持 20(抖音)
keywordstring否抖音号关键词
pageinteger否页码

三个工具的 page 必填性不一致(searchBrands 必填,另两个可选),统一从 1 传起最稳。

3.4  达人 / 店铺 / 商品工具#

kolBaseInfo

参数类型必填说明
ccUidstring是达人 UID,来自 searchKols 返回的 uid 或素材里的 cc_uids

shopSalesMetrics

参数类型必填说明
shop_idsstring是店铺 ID,多个用英文逗号分隔(如 "123,456"),来自 searchShops
startDate / endDatestring是统计日期区间,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首次发现时间 / 趋势指数降序

常用筛选

参数类型说明
keywordstring商品关键词
startDate / endDatestring统计时间范围,YYYY-MM-DD
unitId / product_id_lstID / 数组单品 ID / 商品 ID 列表
shopId / company_idID店铺 ID(来自 searchShops)/ 商家 ID
site_id / category / promotionType / shopType枚举 ID渠道 / 品类 / 推广方式 / 店铺类型
hasBrandint店铺品牌标识:1 有 / 0 无
isNew / isExactboolean新上榜 / 精准搜索
sloganDigestID文案 ID

区间筛选(成对的 min / max 参数)

参数组说明
min_price / max_price价格区间
min_qs_incr_24h / max_qs_incr_24h24h 新增销量区间(另有 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

参数类型必填说明
materialIdstring是素材 ID,来自 searchMaterials
pageinteger是页码
startDate / endDatestring否投放时间范围,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 查达人信息
shopSalesMetricslive_sales 直播销售额 · live_solds 直播销量 · solds 新增销量 · sales 新增销售额(仅此四项)
productSalesRanking商品 ID、商品名称、所属店铺、价格、新增销量、累计销量
materialCreativeList广告文案、流量平台、设备类型、投放日期、投放天数、广告 ID
creativeAIAnalysisDataid(与入参一一对应)、sellPoint(创意卖点)等内容信息;部分素材可能暂无解读内容
creativeAsrid 与口播文案(asr 旁白);无效素材 ID 不返回
searchBrands / searchShops / searchKols候选 ID + 名称列表(品牌另含别名 / 介绍;达人另含昵称)

4返回数据与截断的解决方案#

解决思路(可把这段描述交给 Agent,由它自行生成脚本,无需手写):

脚本直连端点
不经过 MCP 客户端,由脚本直接向端点发起 JSON-RPC 请求(端点和请求头见第 1 节;SSE 响应取 data: 前缀行的 JSON)。直连拿到的是服务端完整响应,不受客户端截断保护影响。
循环翻页
用 page 参数从 1 开始依次翻页,直到取满总量或某页返回条数小于页大小。
原始响应直接落盘
每页写一个本地文件(如 ./mcp_dumps/search_p1.json),数据不经过终端、不进入 Agent 上下文。
终端只打印摘要
仅输出总量、本页条数、落盘路径等统计信息。
分析读文件
后续处理直接读取落盘文件,按需筛出少量样本后再交给 Agent 解读。
环境提示 端点使用 HTTPS,若脚本报 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)
6searchKols 请求需要限定 mediamedia 为必填且当前仅支持 20(抖音),调用时固定传 20
7时间范围超过 180 天searchMaterials 时间窗最大 180 天,更长周期拆成多次调用
8拉全量素材 / 商品榜单页条数固定且按条扣点,请采用「脚本直连 + 逐页落盘」,终端只回传摘要(见第 4 节)
接入问题可联系 有数服务支持获取协助。
MCP 文档