TrueScrape

TrueScrape

通过一个 API 获取公开社交媒体数据：Instagram、TikTok、YouTube、X、 Facebook、LinkedIn、Reddit、Threads 等。个人资料、帖子、视频、 评论、文字稿、广告资料库和指标，全部采用统一的架构。可通过 终端、脚本使用，也可作为 MCP 服务供 Claude、Cursor 和 VS Code 使用。

• 注册即获 1,000 个免费额度，无需银行卡。大多数请求消耗 1 个额度。
• 失败和无结果的请求绝不收费，命中缓存则不消耗额度。
• 额度永不过期。 无订阅；套餐价格为 25 美元起，可获 20,000 个额度。

$ truescrape instagram profile --handle natgeo --pretty
{
  "platform": "instagram",
  "id": "787132",
  "handle": "natgeo",
  "displayName": "National Geographic",
  …
  "verified": true,
  "followerCount": 268245801,
  "followingCount": 195,
  "postCount": 32000,
  …
}
1 credit · live fetch · 1204 ms · req_…

此代码库提供三种方式，可将其接入你的工具和 Agent。

	安装	适用场景
CLI	npm install -g truescrape 或 npx truescrape …	脚本、cron、CI、临时抓取，以及将结果管道传递给 jq
MCP 服务	claude mcp add --transport http truescrape https://api.truescrape.com/mcp --header "x-api-key: YOUR_KEY"	Claude、Cursor、VS Code，以及任何将端点作为工具调用的 MCP 客户端
Agent 技能	npx skills add TrueScrape/truescrape	教 Claude Code、Cursor、Codex、Copilot、Gemini CLI 或 Windsurf 如何高效使用 API

涵盖 45 个平台的 251 个端点，根据 2026-10-30 的实时 API 生成。

tiktok (28) · facebook (22) · instagram (19) · youtube (17) · deezer (11) · github (10) · reddit (9) · google (8) · linkedin (8) · mixcloud (8) · peertube (7) · spotify (7) · twitter (6) · dailymotion (5) · odysee (5) · rumble (5) · substack (5) · threads (5) · amazon (4) · apple-music (4) · bitchute (4) · mastodon (4) · pinterest (4) · redfin (4) · twitch (4) · walmart (4) · bluesky (3) · kwai (3) · snapchat (3) · soundcloud (3) · telegram (3) · truthsocial (3) · zillow (3) · ebay (2) · identity (1) · inference (1) · kick (1) · komi (1) · linkbio (1) · linkme (1) · linktree (1) · milkshake (1) · pillar (1) · solo (1) · taplink (1)

前往 truescrape.com/dashboard 获取密钥。 文档：truescrape.com/docs · OpenAPI · llms.txt

会影响规划的三条规则

1. 失败请求和无结果请求绝不收费。 直接调用即可。
2. 命中缓存不消耗额度。 无需实时数据时，请传入 --cache-max-age 7d（或 cache_max_age=7d）。
3. 多个目标应批量处理，而非循环逐个处理。 每个任务最多可处理 500 个目标。

CLI

npm install -g truescrape          # or: npx truescrape <command>
truescrape auth login              # stores your key (0600) after checking it
truescrape list                    # platforms
truescrape list youtube            # endpoints for one platform
truescrape youtube channel --handle @mkbhd
truescrape youtube channel-videos --handle @mkbhd --all | jq '.items[].viewCount'
truescrape youtube channel --handle @mkbhd --cache-max-age 24h --format table
truescrape batch youtube transcript --targets ids.json --wait
truescrape download https://x.com/<handle>/status/<id> --out ./videos
truescrape balance

truescrape download <post-url> [--out <dir>] [--force] [--json] 可保存来自公开 Instagram、Facebook 或 X 帖子的视频。查询会消耗 1 个额度；如果查询失败，则不消耗额度。文件直接来自平台自有的视频服务器，并会检查其是否使用 https、未经过重定向、是视频且小于 150 MB。YouTube 链接会被拒绝。请只下载你创作的视频或你有权使用的视频。

每个端点都采用 truescrape <platform> <action> --param value 格式。运行任何命令时添加 --help，即可查看参数、费用和跨字段规则。

身份验证，按优先级从高到低：使用 --api-key 进行单次请求（会显示在 shell 历史记录中；请避免用于任何持久用途）；使用 TRUESCRAPE_API_KEY 环境变量（适用于 CI 和 Agent）；然后使用 truescrape auth login 保存的密钥。

输出。 数据以紧凑 JSON 格式写入 stdout；计费信息行（1 credit · live fetch · 412 ms · req_…）写入 stderr，因此管道输出不会受到干扰。

标志	作用
--format json|table|csv|markdown	输出格式（默认为 json）
--pretty	输出缩进的 JSON
--envelope	输出 { data, meta, pagination }，而非 data
--output <path>	将内容写入文件，只打印文件路径
--all, --max-pages <n>	跟随游标并合并页面（默认上限为 10）
--quiet	不输出计费信息行
--verbose	将请求 URL、状态和耗时写入 stderr
--base-url <url>	使用其他 API 来源（也可使用 TRUESCRAPE_BASE_URL）

退出代码：0 表示成功 · 1 表示 API 返回错误 · 2 表示用法或配置错误 · 3 表示无法连接 API。当 stderr 不是终端时，错误会以一行 JSON 格式输出，采用 API 自身的数据结构，并附带响应头中的请求 ID： {"success":false,"error":{"code":"invalid_api_key","message":"…"},"requestId":"req_…"}。 401 始终表示密钥问题，402 始终表示余额问题；CLI 不会混淆二者。

MCP 服务

API 在 https://api.truescrape.com/mcp 提供远程 MCP 服务。每个端点都是一个工具；每次调用都遵循与 HTTP 相同的计费规则。

# Claude Code
claude mcp add --transport http truescrape https://api.truescrape.com/mcp \
  --header "x-api-key: YOUR_KEY" --scope user

# Or let the CLI write the config for you
truescrape agent add claude-code
truescrape agent add cursor            # ~/.cursor/mcp.json (--project for .cursor/mcp.json)
truescrape agent add vscode            # .vscode/mcp.json
truescrape agent add claude-desktop    # claude_desktop_config.json, via the stdio bridge below

Cursor 和 VS Code 的手动配置：

{ "mcpServers": { "truescrape": { "url": "https://api.truescrape.com/mcp", "headers": { "x-api-key": "YOUR_KEY" } } } }

{ "servers": { "truescrape": { "type": "http", "url": "https://api.truescrape.com/mcp", "headers": { "x-api-key": "YOUR_KEY" } } } }

对于只能启动本地进程的客户端，可通过桥接程序使用相同的服务。桥接程序会使用你保存的密钥，将 stdio 转发到远程端点：

{ "mcpServers": { "truescrape": { "command": "npx", "args": ["-y", "truescrape", "mcp"], "env": { "TRUESCRAPE_API_KEY": "YOUR_KEY" } } } }

只加载你需要的平台。 在 URL 中添加 ?platforms=，Agent 就只会看到相应的工具，从而减少上下文占用。CLI 和桥接程序使用相同的平台列表：

claude mcp add --transport http truescrape "https://api.truescrape.com/mcp?platforms=youtube,instagram" \
  --header "x-api-key: YOUR_KEY" --scope user
truescrape agent add cursor --platforms youtube,instagram

无需密钥即可列出工具，因此你可以在注册前查看工具；调用工具则需要密钥。

该服务会在 https://api.truescrape.com/.well-known/mcp 声明其 URL、传输方式和身份验证标头；agent add 会读取这些信息，而不是自行假定。

Agent 技能

truescrape 会向 Agent 介绍端点选择、计费模式、批处理、订阅和平台特性，并从实时 API 生成完整的端点表。两个工作流技能以此为基础：

技能	功能
video-to-content-brief	将样本中的 YouTube 视频整理成附带来源链接的简报，涵盖主题、吸引点和新角度
competitor-content-audit	对比 2 到 5 个 YouTube 频道中相同的近期上传样本

每项技能都会在运行前说明样本数量和费用，并在每条结论旁保留来源视频链接。

npx skills add TrueScrape/truescrape                 # pick from the list; Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf
npx skills add TrueScrape/truescrape --skill video-to-content-brief

作为 Claude Code 插件使用时，会同时安装技能和 MCP 服务（服务会读取 TRUESCRAPE_API_KEY）：

claude plugin marketplace add TrueScrape/truescrape
claude plugin install truescrape@truescrape

该技能位于 skills/truescrape/SKILL.md。 AGENTS.md 是为已经安装 CLI 的 Agent 准备的简短版本。

开发

pnpm install
pnpm test           # vitest
pnpm typecheck
pnpm catalogue      # regenerate src/catalogue.json and the generated blocks from the live API
pnpm build          # dist/index.js

端点目录是自动生成的，切勿手动编辑：当提交的快照与实时 API 不一致时，CI 会失败；当 API 新增端点时，定时任务每天都会创建一个拉取请求。运行捆绑目录中没有记录的命令时，CLI 会先执行一次实时刷新，然后才会放弃。

许可证

MIT。