{
  "markdown": "# tiktok-organic-mcp\n\n[![npm version](https://img.shields.io/npm/v/tiktok-organic-mcp.svg)](https://www.npmjs.com/package/tiktok-organic-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nMCP server for **TikTok organic analytics** — video performance, engagement metrics, and profile insights via the TikTok Developer API.\n\nBuilt for [Claude Code](https://claude.ai/claude-code) and any MCP-compatible AI tool. Gives your AI assistant direct access to your TikTok account data — videos, views, likes, comments, shares, and follower stats.\n\nPart of **[The SEO Engine](https://lanternrow.com/seo-engine/)** toolkit by [Rex Jones](https://rexjones.me) — AI-powered SEO and social media tooling for agencies and businesses.\n\n## Why this exists\n\n- **No open-source TikTok organic MCP existed.** Ads MCPs exist. Organic analytics? Nobody built one.\n- **Paid alternatives cost money.** The commercial options require monthly subscriptions. This is free and open source.\n- **Your AI should see your TikTok data.** Ask \"how are my TikTok videos performing?\" and get a real answer.\n\n## Quick start\n\n### Option 1: npx (no install)\n\n**Single account:**\n\n```json\n{\n  \"mcpServers\": {\n    \"tiktok-organic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tiktok-organic-mcp\"],\n      \"env\": {\n        \"TIKTOK_ACCESS_TOKEN\": \"your_access_token\"\n      }\n    }\n  }\n}\n```\n\n**Multiple accounts:**\n\n```json\n{\n  \"mcpServers\": {\n    \"tiktok-organic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tiktok-organic-mcp\"],\n      \"env\": {\n        \"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\\\"}]\"\n      }\n    }\n  }\n}\n```\n\n### Option 2: Clone and build\n\n```bash\ngit clone https://github.com/lanternrow/tiktok-organic-mcp.git\ncd tiktok-organic-mcp\nnpm install\nnpm run build\n```\n\nThen add to your Claude Code MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"tiktok-organic\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/tiktok-organic-mcp/dist/index.js\"],\n      \"env\": {\n        \"TIKTOK_ACCESS_TOKEN\": \"your_access_token\"\n      }\n    }\n  }\n}\n```\n\n## Getting your TikTok Access Token\n\n### Step 1: Create a TikTok Developer App\n\n1. Go to the [TikTok Developer Portal](https://developers.tiktok.com/) and log in\n2. Click **Manage apps** → **Connect an app**\n3. Fill in your app details and submit for review\n\n### Step 2: Add Login Kit and request scopes\n\n1. In your app dashboard, add the **Login Kit** product\n2. Request these scopes:\n   - `user.info.basic` — profile name, avatar\n   - `user.info.profile` — bio, verification status\n   - `user.info.stats` — follower/following counts, total likes\n   - `video.list` — access to video listing and metrics\n\n### Step 3: Complete the OAuth flow\n\n1. Direct users to TikTok's authorization URL:\n   ```\n   https://www.tiktok.com/v2/auth/authorize/\n     ?client_key={your_client_key}\n     &scope=user.info.basic,user.info.profile,user.info.stats,video.list\n     &response_type=code\n     &redirect_uri={your_redirect_uri}\n   ```\n2. Exchange the authorization code for tokens:\n   ```\n   POST https://open.tiktokapis.com/v2/oauth/token/\n   Content-Type: application/x-www-form-urlencoded\n\n   client_key={client_key}\n   &client_secret={client_secret}\n   &code={auth_code}\n   &grant_type=authorization_code\n   &redirect_uri={redirect_uri}\n   ```\n3. Save the `access_token` and `refresh_token` from the response\n\n> **Tip:** Access tokens expire after 24 hours. Use the `refresh_token` tool or set `TIKTOK_REFRESH_TOKEN` to enable automatic renewal.\n\n## Multi-account support\n\nMonitor multiple TikTok accounts from a single MCP server. Set the `TIKTOK_ACCOUNTS` environment variable as a JSON array:\n\n```json\n[\n  {\n    \"name\": \"mybrand\",\n    \"access_token\": \"act.xxx\",\n    \"client_key\": \"abc123\",\n    \"refresh_token\": \"rft.xxx\"\n  },\n  {\n    \"name\": \"otherbrand\",\n    \"access_token\": \"act.yyy\",\n    \"client_key\": \"def456\",\n    \"refresh_token\": \"rft.yyy\"\n  }\n]\n```\n\nEach account object requires:\n- `name` — a unique label you pick (used in tool calls)\n- `access_token` — the OAuth access token\n\nOptional:\n- `client_key` — needed for token refresh\n- `refresh_token` — needed for token refresh\n\n**Using accounts in tools:** Every tool accepts an optional `account` parameter. If omitted, the first account in the array is used as default.\n\n```\nget_user_info(account: \"mybrand\")\nget_videos(account: \"otherbrand\", max_count: 10)\n```\n\n**Backward compatible:** If you only have one account, the legacy single-env-var format (`TIKTOK_ACCESS_TOKEN`) still works. It creates a default account named \"default\".\n\n## Tools\n\n### Account tools\n\n| Tool | Description |\n|------|-------------|\n| `list_accounts` | List all configured TikTok accounts and the default |\n\n### Read tools\n\n| Tool | Description |\n|------|-------------|\n| `get_user_info` | Profile metadata: username, bio, follower/following counts, total likes, video count, verification status |\n| `get_videos` | Paginated list of public videos with engagement metrics (views, likes, comments, shares) |\n| `get_video_details` | Detailed metrics for specific video IDs (batch up to 20) |\n\n### Utility tools\n\n| Tool | Description |\n|------|-------------|\n| `refresh_token` | Exchange refresh token for a new access token (requires `client_key` and `refresh_token` in account config) |\n\nAll read and utility tools accept an optional `account` parameter to target a specific account.\n\n## Architecture\n\n```\nsrc/\n  index.ts          # MCP server entry point, tool registration\n  accounts.ts       # Multi-account resolution and configuration\n  client.ts         # TikTok API HTTP client (native fetch, no dependencies)\n  types.ts          # TypeScript interfaces for API responses\n  tools/\n    user.ts         # get_user_info\n    videos.ts       # get_videos, get_video_details\n    utils.ts        # refresh_token\n```\n\n- **Zero external HTTP dependencies** — uses Node 18+ native `fetch`\n- **Multi-account support** — monitor multiple TikTok accounts from one server\n- **Backward compatible** — single-token env var still works\n- **Cursor-based pagination** — video listing supports pagination via cursor\n- **Zod validation** — all tool inputs validated with descriptive error messages\n- **Batch video queries** — get details for up to 20 videos in one request\n\n## Environment variables\n\n### Multi-account (recommended)\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `TIKTOK_ACCOUNTS` | Yes | JSON array of account objects (see Multi-account support section) |\n\n### Single account (legacy)\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `TIKTOK_ACCESS_TOKEN` | Yes | OAuth access token from Login Kit flow |\n| `TIKTOK_CLIENT_KEY` | For refresh | App Client Key (needed for token refresh) |\n| `TIKTOK_REFRESH_TOKEN` | For refresh | Refresh token (needed for token refresh) |\n\n## Development\n\n```bash\nnpm run dev    # Watch mode — recompiles on save\nnpm run build  # Production build\nnpm start      # Run the server\n```\n\n## Contributing\n\nIssues and PRs welcome. If TikTok changes their API, please open an issue.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\nBuilt as part of **The SEO Engine** by [Rex Jones](https://rexjones.me).\n",
  "bytes": 7399,
  "sha": "c8bba892cccb7b4ba477aae18f9c2ff1a88b10ae4dcad62676c7d085787c321d",
  "repo_slug": "lanternrow/tiktok-organic-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lanternrow_tiktok_organic_mcp_9649d9dc/readme"
}