tokportal-mcp

TokPortal은 관리형 소셜 인프라 API입니다. 16개 이상의 국가에서 인간 계정 관리자가 생성, 예열, 운영하는 실제 TikTok, Instagram, YouTube 계정을 REST API 및 MCP 서버로 제공합니다. 계정별 OAuth, 하루 25개 게시물 제한, 앱 리뷰가 없습니다.

문서 https://developers.tokportal.com · API 기본 URL 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 · llms.txt https://developers.tokportal.com/llms.txt

tokportal-mcp는 TokPortal API 공식 Model Context Protocol 서버입니다. 모든 공개 API 작업(91개 도구)을 Claude, Cursor, VS Code, Windsurf, Codex, Gemini CLI 및 기타 MCP 클라이언트에 노출합니다. 번들 생성, 동영상 업로드, 계정 구성 및 게시, 분석 조회, 웹훅 관리 등을 수행할 수 있습니다.

두 가지 사용 방법:

로컬 서버를 사용하려면 Node.js 20 이상이 필요합니다. https://app.tokportal.com/developer/api-keys에서 API 키를 발급받으세요(형식: sk_ + 64자리 16진수).

30초 퀵스타트

npm install -g tokportal-mcp
TOKPORTAL_API_KEY=sk_your_key_here tokportal-mcp

서버는 stdio를 통해 MCP를 사용합니다. MCP 클라이언트에서 이를 지정하고 예를 들어 다음과 같이 요청하세요:

"미국에서 5개의 동영상으로 TikTok 번들을 생성하고, ./launch.mp4를 첫 번째 동영상으로 'Day 1' 캡션과 함께 업로드한 후 번들을 게시하세요."

해당 호출 체인은 tokportal_create_bundle → tokportal_upload_video_direct → tokportal_configure_bundle_video → tokportal_publish_bundle을 사용합니다.

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(); // 91 tools
const me = await client.callTool({ name: "tokportal_get_current_user", arguments: {} });
console.log(tools.length, me.content[0].text);

클라이언트 구성

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 에이전트 모드)

.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 작업을 MCP 도구로 stdio를 통해 노출합니다. 공개 API 스키마에서 생성되며 HTTP API와 동일한 X-API-Key 인증을 사용합니다.

• 도구 이름은 tokportal_<operation_id_snake_case> 형식입니다 (tokportal_create_bundle, tokportal_list_accounts, ...). 경로 및 쿼리 매개변수는 최상위 입력이며, JSON 본문은 body에 들어갑니다.

• 모든 도구는 MCP 주석을 포함합니다: title, readOnlyHint (GET), destructiveHint (DELETE / 취소 / 게시 취소 / 재설정 / 예약 취소 / 철회), idempotentHint (GET/PUT/DELETE) 및 openWorldHint: false. 따라서 클라이언트는 파괴적인 호출에 대해 확인을 요청할 수 있습니다.

• 멀티파트 업로드 도구도 OpenAPI에서 생성됩니다. 바이너리 필드는 file_path와 같은 로컬 경로 입력으로 노출되며, 나머지 폼 필드는 스키마 이름으로 노출됩니다.

• 변경 작업은 선택적 idempotency_key (Idempotency-Key로 전송)를 허용합니다. 단, 비밀 관련 작업(자격 증명 공개, 인증 코드, 웹훅 생성, 서명된 업로드 URL, 보고서 생성)은 재생되지 않습니다.

MCP 서버는 관찰 가능성 및 지원 진단을 위해 API 요청 시 X-TokPortal-Client: tokportal-mcp/1.12.1을 전송합니다.

실패한 도구 호출은 diagnostics 객체(request_id, retry_after_seconds, rate_limit 포함)가 포함된 오류 결과를 반환합니다. 해당 헤더를 사용할 수 있는 경우에만 포함됩니다.

전역 설치된 바이너리를 사용하는 레거시 구성도 여전히 작동합니다:

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

진실의 원천

이 패키지는 TokPortal 공개 OpenAPI 스키마(https://developers.tokportal.com/openapi.json)에서 비공개 TokPortal 모노레포에서 생성됩니다. src/generated.ts는 릴리스마다 다시 생성되므로 수동으로 편집하지 마십시오. PR로 허용되는 내용은 CONTRIBUTING.md를, 취약점 보고는 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