{
  "markdown": "# tokportal-mcp\n\n[![npm](https://img.shields.io/npm/v/tokportal-mcp.svg)](https://www.npmjs.com/package/tokportal-mcp)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nTokPortal is the managed social infrastructure API: real TikTok, Instagram and YouTube accounts created, warmed and operated by human account managers in 16+ countries — exposed as a REST API and an MCP server. No OAuth per account, no 25-posts/day cap, no app review.\n\nDocs https://developers.tokportal.com · API base https://app.tokportal.com/api/ext · OpenAPI https://developers.tokportal.com/openapi.json · MCP remote https://app.tokportal.com/api/ext/mcp · Get an API key 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\n\n---\n\n`tokportal-mcp` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for the TokPortal API. It exposes every public API operation (91 tools) to Claude, Cursor, VS Code, Windsurf, Codex, Gemini CLI and any other MCP client — create bundles, upload videos, configure and publish accounts, read analytics, manage webhooks.\n\nTwo ways to use it:\n\n| Mode | Transport | When to use |\n| --- | --- | --- |\n| **Local** (`npx tokportal-mcp`) | stdio | Desktop clients, local agents, file uploads from disk |\n| **Remote** (`https://app.tokportal.com/api/ext/mcp`) | Streamable HTTP | Hosted agents, no install; same tool catalogue |\n\nRequires Node.js 20 or newer. The local server runs on it directly. Get an API key at https://app.tokportal.com/developer/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=tokportal-mcp (format `sk_` + 64 hex chars).\n\n## 30-second quickstart\n\n```bash\nnpm install -g tokportal-mcp\nTOKPORTAL_API_KEY=sk_your_key_here tokportal-mcp\n```\n\nThe server speaks MCP over stdio. Point any MCP client at it and ask, for example:\n\n> \"Create a TikTok bundle in the USA with 5 videos, upload `./launch.mp4` as video 1 with the caption 'Day 1', then publish the bundle.\"\n\nThat call chain uses `tokportal_create_bundle` → `tokportal_upload_video_direct` → `tokportal_configure_bundle_video` → `tokportal_publish_bundle`.\n\nProgrammatic smoke test with the MCP SDK:\n\n```js\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst client = new Client({ name: \"demo\", version: \"1.0.0\" });\nawait client.connect(\n  new StdioClientTransport({\n    command: \"npx\",\n    args: [\"-y\", \"tokportal-mcp\"],\n    env: { ...process.env, TOKPORTAL_API_KEY: process.env.TOKPORTAL_API_KEY },\n  }),\n);\n\nconst { tools } = await client.listTools(); // 91 tools\nconst me = await client.callTool({ name: \"tokportal_get_current_user\", arguments: {} });\nconsole.log(tools.length, me.content[0].text);\n```\n\n## Client configuration\n\nReplace `sk_your_key_here` with your key. Every snippet below is the local stdio server; the remote URL variant is listed at the end.\n\n### Cursor\n\n`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):\n\n```json\n{\n  \"mcpServers\": {\n    \"tokportal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tokportal-mcp\"],\n      \"env\": { \"TOKPORTAL_API_KEY\": \"sk_your_key_here\" }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\n`claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\\Claude\\`):\n\n```json\n{\n  \"mcpServers\": {\n    \"tokportal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tokportal-mcp\"],\n      \"env\": { \"TOKPORTAL_API_KEY\": \"sk_your_key_here\" }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add tokportal -e TOKPORTAL_API_KEY=sk_your_key_here -- npx -y tokportal-mcp\n# or the remote server:\nclaude mcp add --transport http tokportal https://app.tokportal.com/api/ext/mcp --header \"X-API-Key: sk_your_key_here\"\n```\n\n### VS Code (GitHub Copilot agent mode)\n\n`.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"tokportal\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tokportal-mcp\"],\n      \"env\": { \"TOKPORTAL_API_KEY\": \"sk_your_key_here\" }\n    }\n  }\n}\n```\n\n### Windsurf\n\n`~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokportal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tokportal-mcp\"],\n      \"env\": { \"TOKPORTAL_API_KEY\": \"sk_your_key_here\" }\n    }\n  }\n}\n```\n\n### OpenAI Codex CLI\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.tokportal]\ncommand = \"npx\"\nargs = [\"-y\", \"tokportal-mcp\"]\nenv = { TOKPORTAL_API_KEY = \"sk_your_key_here\" }\n```\n\n### Gemini CLI\n\n`~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokportal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tokportal-mcp\"],\n      \"env\": { \"TOKPORTAL_API_KEY\": \"sk_your_key_here\" }\n    }\n  }\n}\n```\n\n### Remote server (Streamable HTTP)\n\nAny client that supports remote MCP servers can connect to\n`https://app.tokportal.com/api/ext/mcp` with either an `X-API-Key: sk_...` header\nor `Authorization: Bearer sk_...`. Example for clients using the `url` form:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokportal\": {\n      \"url\": \"https://app.tokportal.com/api/ext/mcp\",\n      \"headers\": { \"X-API-Key\": \"sk_your_key_here\" }\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `TOKPORTAL_API_KEY` | yes | API key (`sk_` + 64 hex). Only a SHA-256 hash is stored server-side. |\n| `TOKPORTAL_BASE_URL` | no | Defaults to `https://app.tokportal.com/api/ext`. |\n\n## How the tools work\n\nThe server exposes TokPortal API actions as MCP tools over stdio. It is generated from the public API schema and uses the same `X-API-Key` authentication as the HTTP API.\n\n- Tool names are `tokportal_<operation_id_snake_case>` (`tokportal_create_bundle`, `tokportal_list_accounts`, ...). Path and query parameters are top-level inputs; JSON bodies go in `body`.\n- Every tool carries MCP annotations: `title`, `readOnlyHint` (GET), `destructiveHint` (DELETE / cancel / unpublish / reset / unschedule / revoke), `idempotentHint` (GET/PUT/DELETE) and `openWorldHint: false`, so clients can ask for confirmation on destructive calls.\n- Multipart upload tools are generated from OpenAPI too. Binary fields are exposed as local path inputs such as `file_path`, with the remaining form fields exposed by their schema names.\n- Mutations accept an optional `idempotency_key` (sent as `Idempotency-Key`) except for secret-bearing operations (credential reveal, verification codes, webhook creation, signed upload URLs, report creation) which are never replayed.\n\nThe MCP server sends `X-TokPortal-Client: tokportal-mcp/1.15.0` on API requests for observability and support diagnostics.\n\nFailed tool calls return an error result with a `diagnostics` object containing `request_id`, `retry_after_seconds`, and `rate_limit` when those headers are available.\n\nLegacy config using the globally installed binary still works:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokportal\": {\n      \"command\": \"tokportal-mcp\",\n      \"env\": {\n        \"TOKPORTAL_API_KEY\": \"sk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n## Source of truth\n\nThis package is generated from the TokPortal public OpenAPI schema\n(https://developers.tokportal.com/openapi.json) in the private TokPortal\nmonorepo. `src/generated.ts` is regenerated on every release — do not edit it by\nhand. See [CONTRIBUTING.md](./CONTRIBUTING.md) for what we accept as PRs and\n[SECURITY.md](./SECURITY.md) for vulnerability reporting.\n\n## Links\n\n- Documentation: https://developers.tokportal.com\n- MCP guide: https://developers.tokportal.com/mcp\n- SDKs & CLI: https://developers.tokportal.com/sdks-cli\n- API reference (OpenAPI): https://developers.tokportal.com/openapi.json\n- Other packages: [`@tokportal/node`](https://www.npmjs.com/package/@tokportal/node) · [`@tokportal/cli`](https://www.npmjs.com/package/@tokportal/cli) · [`tokportal` (PyPI)](https://pypi.org/project/tokportal/) · [`github.com/tokportal/tokportal-go`](https://github.com/tokportal/tokportal-go)\n\nMIT © TokPortal\n",
  "bytes": 7977,
  "sha": "bf1f28529f1a8fa89a9d0ca97e5cf2003bcdcc5b381127399bfd5e0e676dfc7a",
  "repo_slug": "tokportal/tokportal-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_tokportal_mcp_acdb9ac5/readme"
}