TokPortal

tokportal-mcp

TokPortal 是一套托管式社交基础设施 API：由人工账号经理在 16+ 个国家/地区创建、预热并运营真实的 TikTok 和 Instagram 品牌账号，并通过 REST API 和 MCP 服务提供。无需通过 OAuth 连接每个社交账号，即可在不同市场间进行地理分片。此 API 不支持创建 YouTube 套餐。

使用沙盒前请先升级： 本地 tokportal-mcp 需要 1.15.1 或更高版本才能使用 dry_run。1.15.0 虽然声明支持该参数，却没有发送沙盒标头，因此预览操作可能会执行真实操作。请更新本地服务，或使用远程连接器。

文档 https://developers.tokportal.com · API 基础地址 https://app.tokportal.com/api/ext · OpenAPI https://developers.tokportal.com/openapi.json · MCP 远程服务 https://app.tokportal.com/api/ext/mcp · 获取 API 密钥 https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp · llms.txt https://developers.tokportal.com/llms.txt

---

tokportal-mcp 是 TokPortal API 的官方 Model Context Protocol 服务。其核心工具可继续供 Claude、Cursor、VS Code、Windsurf、Codex、Gemini CLI 和其他 MCP 客户端使用。为工作区启用 AI 后，还会提供七个额外的精选工具，涵盖模型发现、报价生成、媒体管理和独立的 AI 美元钱包。模型专属的架构会按需获取，而不会以数百个工具的形式公开。

两种使用方式：

模式	传输方式	适用场景
本地（npx tokportal-mcp）	stdio	桌面客户端、本地 Agent、从磁盘上传文件
远程（https://app.tokportal.com/api/ext/mcp）	Streamable HTTP	托管式 Agent，无需安装；工具目录相同

需要 Node.js 20 或更高版本。本地服务可直接在其上运行。请在 https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp 获取 API 密钥（格式为 sk_ + 64 个十六进制字符）。

30 秒快速入门

npm install -g [email protected]
TOKPORTAL_API_KEY=sk_your_key_here tokportal-mcp

该服务通过 stdio 使用 MCP 通信。将任意 MCP 客户端指向它，然后提出如下请求：

“读取可用国家/地区、积分价格和我的余额。预览一个位于美国的仅账号 TikTok 套餐，并设置 dry_run: true。告诉我即时费用和周期性费用，并在任何实际购买前等我确认 GO。”

预览会使用 { "dry_run": true, "body": { "bundle_type": "account_only", "platform": "tiktok", "country": "USA" } } 调用 tokportal_create_bundle。该操作会验证请求，并返回 credits_would_charge，同时将 credits_charged 设为 0，不会创建任何任务。以实际模式创建会立即扣费。预览 ID 是模拟 ID，绝不能在实际请求中重复使用。收到 GO 后，请创建真实资源并使用其实际 ID。请参阅沙盒约定。

使用 MCP SDK 进行编程式冒烟测试：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const client = new Client({ name: "demo", version: "1.0.0" });
await client.connect(
  new StdioClientTransport({
    command: "npx",
    args: ["-y", "tokportal-mcp"],
    env: { ...process.env, TOKPORTAL_API_KEY: process.env.TOKPORTAL_API_KEY },
  }),
);

const { tools } = await client.listTools(); // Core tools, plus 7 when AI is enabled
const me = await client.callTool({ name: "tokportal_get_current_user", arguments: {} });
console.log(tools.length, me.content[0].text);

AI 生成（分阶段开放）

AI 发现功能会通过经过身份验证的 GET /ai/status 调用进行检查。如果不可用，则只显示现有目录；不会回退到其他提供商，也不会自动付款。本地 AI 支持要求版本为 1.16.0 或更高，并且服务端已开放。安装此软件包不会启用生成、授予消费权限或激活账单。版本 1.15.1 保留现有账户管理工具，但不包含 AI 发现功能。远程可用性由服务端控制。

生成需要 body: { quote_id, max_cost_usd } 和 idempotency_key。如果响应状态不确定，请重用同一个键。报价会在 15 分钟内过期；请使用返回的过期时间。AI 美元钱包与账户管理积分相互独立。AI 工具不接受旧版 dry_run 合约；请使用报价操作，该操作不会启动付费的提供商任务。取消仅尽力而为，不保证退款。创建操作不会发布内容：请先检查返回的素材，然后使用现有的 TokPortal 排期工具。

客户端配置

将 sk_your_key_here 替换为你的密钥。以下所有代码片段都是本地 stdio 服务；远程 URL 形式列于末尾。

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}

Claude Desktop

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}

Claude Code

claude mcp add tokportal -e TOKPORTAL_API_KEY=sk_your_key_here -- npx -y tokportal-mcp
# or the remote server:
claude mcp add --transport http tokportal https://app.tokportal.com/api/ext/mcp --header "X-API-Key: sk_your_key_here"

VS Code（GitHub Copilot Agent 模式）

.vscode/mcp.json：

{
  "servers": {
    "tokportal": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}

OpenAI Codex CLI

~/.codex/config.toml：

[mcp_servers.tokportal]
command = "npx"
args = ["-y", "tokportal-mcp"]
env = { TOKPORTAL_API_KEY = "sk_your_key_here" }

Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "tokportal": {
      "command": "npx",
      "args": ["-y", "tokportal-mcp"],
      "env": { "TOKPORTAL_API_KEY": "sk_your_key_here" }
    }
  }
}

远程服务（Streamable HTTP）

任何支持远程 MCP 服务的客户端都可以通过 X-API-Key: sk_... 标头或 Authorization: Bearer sk_... 连接到 https://app.tokportal.com/api/ext/mcp。以下是使用 url 形式的客户端示例：

{
  "mcpServers": {
    "tokportal": {
      "url": "https://app.tokportal.com/api/ext/mcp",
      "headers": { "X-API-Key": "sk_your_key_here" }
    }
  }
}

环境变量

变量	必需	描述
TOKPORTAL_API_KEY	是	API 密钥（sk_ + 64 位十六进制数）。服务端仅存储 SHA-256 哈希值。
TOKPORTAL_BASE_URL	否	默认为 https://app.tokportal.com/api/ext。

工具的工作方式

该服务通过 stdio 将 TokPortal API 操作公开为 MCP 工具。它根据公开的 API 架构生成，并使用与 HTTP API 相同的 X-API-Key 身份验证方式。

• 工具名称为 tokportal_<operation_id_snake_case>（tokportal_create_bundle、tokportal_list_accounts 等）。路径和查询参数是顶层输入；JSON 请求体放在 body 中。
• 每个工具都带有 title、readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint。请阅读每个工具的注释：付费操作和不可逆操作即使不会删除任何内容，也可能具有破坏性。
• 每个非 GET 工具都接受顶层参数 dry_run: true，并将其作为 X-TokPortal-Dry-Run: true 发送。它绝不会放在查询参数或请求体中。试运行会消耗正常的速率限制，但不会消耗 idempotency_key；如果后续正式请求的操作支持幂等性，请使用同一个键。
• Multipart 上传工具也由 OpenAPI 生成。二进制字段会以 file_path 等本地路径输入的形式公开，其余表单字段则使用架构中定义的名称。
• 除涉及机密的操作（凭据显示、验证码、Webhook 创建、签名上传 URL、报告创建）外，所有变更操作都接受可选的 idempotency_key（作为 Idempotency-Key 发送）；这些涉及机密的操作绝不会重放。

MCP 服务会在 API 请求中发送 X-TokPortal-Client: tokportal-mcp/1.22.0，用于可观测性和支持诊断。

工具调用失败时会返回错误结果，其中包含 diagnostics 对象；如果相关标头可用，该对象将包含 request_id、retry_after_seconds 和 rate_limit。

使用全局安装二进制文件的旧版配置仍然有效：

{
  "mcpServers": {
    "tokportal": {
      "command": "tokportal-mcp",
      "env": {
        "TOKPORTAL_API_KEY": "sk_your_key_here"
      }
    }
  }
}

信息源

此包由私有 TokPortal monorepo 中的 TokPortal 公共 OpenAPI 架构生成 （https://developers.tokportal.com/openapi.json）。每次发布都会重新生成 src/generated.ts，请勿手动编辑。请参阅 CONTRIBUTING.md，了解我们接受哪些 PR；漏洞报告请参阅 SECURITY.md。

链接

• 文档：https://developers.tokportal.com
• MCP 指南：https://developers.tokportal.com/mcp
• SDK 和 CLI：https://developers.tokportal.com/sdks-cli
• API 参考（OpenAPI）：https://developers.tokportal.com/openapi.json
• 其他包：@tokportal/node · @tokportal/cli · tokportal (PyPI) · github.com/tokportal/tokportal-go

MIT © TokPortal

已关联的分析数据（1.18.0）

使用 tokportal_get_analytics_account_insights 和 { "id": "saved-account-uuid" } 读取 Instagram 账户周期的覆盖人数、浏览量和互动数据，以及符合条件的 TikTok 帖子观看时长、完播率和流量数据。需要 Creator 或更高等级；现有等级限制仍然有效。账户未关联或未经验证时，返回 available: false 和 connected_analytics: null。此操作为只读，不会启动刷新。缺失的指标会被省略；完播率为 0–1 的小数，流量和受众细分为 0–100 的百分比，观看时长以秒为单位。同一数据块也会出现在 tokportal_get_analytics_account 中。完整契约。

收件箱操作和 Business 设置（1.19.0）

使用 tokportal_get_account_inbox 读取限定范围的已收到评论和 Instagram 消息。使用 tokportal_create_account_comment_reply 公开回复（0 积分，需要签名回复能力、稳定的请求键、当前 Coverage 和账户配额）。使用 tokportal_get_account_comment_reply 检查发送状态；对于未知结果，切勿盲目重发。

tokportal_get_account_business_setup 用于读取进度；在明确确认音乐限制后，每个 Instagram 账户可使用 tokportal_request_account_business_setup 以 5 积分下单请求经理处理任务，每个账户限一次。TikTok 私信不可用。公开元数据 Webhook 会通知连接、收到的活动、回复结果和 Business 任务变更。有关契约和限制，请参阅 Connection & Inbox 指南。

关键词评论审核

tokportal_get_account_comment_moderation 用于读取账户规则和结果历史记录。 tokportal_update_account_comment_moderation 用于保存 Instagram 和 TikTok 的明确关键词/例外规则。请先读取设置版本。默认禁用；不发送私信，也不扣除积分。保存后仅处理新评论。目前 TikTok 取消隐藏的功能不可靠，禁用规则不会恢复已隐藏的评论。使用 dry_run: true 可在不保存的情况下进行验证。

Instagram 消息和评论转私信

在收到消息后的 24 小时内，使用 tokportal_send_account_inbox_message 回复现有 Instagram 对话。每条评论在七天内使用一次 tokportal_create_account_private_reply。当连接权限允许时，创作者和 Business 账号均符合条件。通过 tokportal_get_account_inbox 获取与账号绑定的引用；不接受任意收件人 ID。这些操作目前不收取积分。

tokportal_get_account_comment_dm 和 tokportal_update_account_comment_dm 用于管理每个账号的一条自愿订阅关键词规则，也可选择将规则限定到自有帖子。规则默认处于禁用状态，仅处理新的原创评论，并提供持久化历史记录。共享账号冷却时间、Coverage、严格的身份检查和持久化请求键去重均适用。投递状态未知时，绝不能盲目重发。使用 tokportal_get_account_message_operation 查询状态。仅发送私信回复并不意味着可以继续发送后续私信。目前不提供 TikTok 私信。

完整指南：https://developers.tokportal.com/account-connection-inbox

手动评论控制（1.22.0）

仅当评论返回的 actions 中包含相应操作时，tokportal_create_account_comment_action 才支持删除、隐藏、Instagram 取消隐藏，以及 TikTok 顶层评论置顶/取消置顶。传入准确的签名操作引用和帖子引用。永久删除前，先向用户确认。费用为 0 积分。服务器会在预留共享账号租约前检查权限、Coverage、当前连接和服务提供商能力。使用稳定的 request_key；结果不确定时，使用 tokportal_get_account_comment_action 查询。绝不要盲目重复仍在等待或状态未知的写入操作。dry_run: true 可在不修改评论的情况下进行验证。inbox.comment.action.updated 仅包含结果元数据。本次发布不提供 TikTok 取消隐藏和点赞功能。请等待 Retry-After；配额并非安全的活动目标，也无法保证账号不会受到限制。