tiktok-organic-mcp

tiktok-organic-mcp

用于 TikTok 自然流量分析 的 MCP 服务——通过 TikTok Developer API 获取视频表现、互动指标和个人资料洞察。

专为 Claude Code 及所有兼容 MCP 的 AI 工具打造。让你的 AI 助手直接访问 TikTok 账户数据——视频、观看次数、点赞、评论、分享和粉丝统计。

这是 Rex Jones 的 The SEO Engine 工具集的一部分，提供面向代理机构和企业的 AI 驱动 SEO 与社交媒体工具。

为什么要开发它

• 此前没有开源的 TikTok 自然流量 MCP。 已有广告 MCP，但没人开发自然流量分析工具。
• 付费替代方案需要花钱。 商业方案需要按月订阅。本项目免费且开源。
• 你的 AI 应该能查看 TikTok 数据。 询问“我的 TikTok 视频表现如何？”，就能获得真实答案。

快速开始

选项 1：npx（无需安装）

单个账户：

{
  "mcpServers": {
    "tiktok-organic": {
      "command": "npx",
      "args": ["-y", "tiktok-organic-mcp"],
      "env": {
        "TIKTOK_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

多个账户：

{
  "mcpServers": {
    "tiktok-organic": {
      "command": "npx",
      "args": ["-y", "tiktok-organic-mcp"],
      "env": {
        "TIKTOK_ACCOUNTS": "[{\"name\":\"mybrand\",\"access_token\":\"act.xxx\",\"client_key\":\"abc123\",\"refresh_token\":\"rft.xxx\"},{\"name\":\"otherbrand\",\"access_token\":\"act.yyy\",\"client_key\":\"def456\",\"refresh_token\":\"rft.yyy\"}]"
      }
    }
  }
}

选项 2：克隆并构建

git clone https://github.com/lanternrow/tiktok-organic-mcp.git
cd tiktok-organic-mcp
npm install
npm run build

然后将其添加到 Claude Code MCP 设置中：

{
  "mcpServers": {
    "tiktok-organic": {
      "command": "node",
      "args": ["/path/to/tiktok-organic-mcp/dist/index.js"],
      "env": {
        "TIKTOK_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

获取 TikTok Access Token

第 1 步：创建 TikTok Developer App

1. 前往 TikTok Developer Portal 并登录
2. 点击 Manage apps → Connect an app
3. 填写应用详情并提交审核

第 2 步：添加 Login Kit 并申请权限范围

1. 在应用控制面板中添加 Login Kit 产品
2. 申请以下权限范围：
   • user.info.basic — 个人资料名称、头像
   • user.info.profile — 简介、认证状态
   • user.info.stats — 粉丝数、关注数、点赞总数
   • video.list — 访问视频列表及指标

第 3 步：完成 OAuth 流程

1. 将用户引导至 TikTok 授权 URL：

   https://www.tiktok.com/v2/auth/authorize/
     ?client_key={your_client_key}
     &scope=user.info.basic,user.info.profile,user.info.stats,video.list
     &response_type=code
     &redirect_uri={your_redirect_uri}
   

2. 使用授权码换取令牌：

   POST https://open.tiktokapis.com/v2/oauth/token/
   Content-Type: application/x-www-form-urlencoded
   
   client_key={client_key}
   &client_secret={client_secret}
   &code={auth_code}
   &grant_type=authorization_code
   &redirect_uri={redirect_uri}
   

3. 保存响应中的 access_token 和 refresh_token

提示： Access Token 会在 24 小时后过期。使用 refresh_token 工具，或设置 TIKTOK_REFRESH_TOKEN，即可启用自动续期。

多账户支持

通过单个 MCP 服务监控多个 TikTok 账户。将 TIKTOK_ACCOUNTS 环境变量设置为 JSON 数组：

[
  {
    "name": "mybrand",
    "access_token": "act.xxx",
    "client_key": "abc123",
    "refresh_token": "rft.xxx"
  },
  {
    "name": "otherbrand",
    "access_token": "act.yyy",
    "client_key": "def456",
    "refresh_token": "rft.yyy"
  }
]

每个账户对象都需要：

• name — 自选的唯一标签（用于工具调用）
• access_token — OAuth Access Token

可选项：

• client_key — 刷新令牌时需要
• refresh_token — 刷新令牌时需要

在工具中使用账户： 每个工具都接受可选的 account 参数。若省略，则使用数组中的第一个账户作为默认账户。

get_user_info(account: "mybrand")
get_videos(account: "otherbrand", max_count: 10)

向后兼容： 如果只有一个账户，仍可使用旧版单环境变量格式（TIKTOK_ACCESS_TOKEN）。此格式会创建一个名为“default”的默认账户。

工具

账户工具

工具	描述
list_accounts	列出所有已配置的 TikTok 账户及默认账户

读取工具

工具	描述
get_user_info	个人资料元数据：用户名、简介、粉丝数/关注数、点赞总数、视频数、认证状态
get_videos	分页列出公开视频及互动指标（观看次数、点赞、评论、分享）
get_video_details	获取指定视频 ID 的详细指标（单次最多 20 个）

实用工具

工具	描述
refresh_token	使用刷新令牌换取新的 Access Token（账户配置中需要提供 client_key 和 refresh_token）

所有读取和实用工具都接受可选的 account 参数，用于指定目标账户。

架构

src/
  index.ts          # MCP server entry point, tool registration
  accounts.ts       # Multi-account resolution and configuration
  client.ts         # TikTok API HTTP client (native fetch, no dependencies)
  types.ts          # TypeScript interfaces for API responses
  tools/
    user.ts         # get_user_info
    videos.ts       # get_videos, get_video_details
    utils.ts        # refresh_token

• 不依赖外部 HTTP 库 — 使用 Node 18+ 内置的 fetch
• 支持多个账号 — 可通过一个服务监控多个 TikTok 账号
• 向后兼容 — 仍可使用单个令牌环境变量
• 基于游标的分页 — 视频列表支持通过游标分页
• Zod 验证 — 验证所有工具输入，并提供清晰的错误消息
• 批量查询视频 — 一次请求最多可获取 20 个视频的详情

环境变量

多账号（推荐）

变量	必填	说明
TIKTOK_ACCOUNTS	是	账号对象的 JSON 数组（参见“多账号支持”部分）

单账号（旧版）

变量	必填	说明
TIKTOK_ACCESS_TOKEN	是	来自 Login Kit 流程的 OAuth 访问令牌
TIKTOK_CLIENT_KEY	用于刷新	应用 Client Key（刷新令牌时需要）
TIKTOK_REFRESH_TOKEN	用于刷新	刷新令牌（刷新令牌时需要）

开发

npm run dev    # Watch mode — recompiles on save
npm run build  # Production build
npm start      # Run the server

贡献

欢迎提交问题和 PR。如果 TikTok 更改了其 API，请提交一个问题。

许可证

MIT — 参见 LICENSE。

---

由 Rex Jones 开发，作为 The SEO Engine 的一部分。