Tiktok Organic Mcp

tiktok-organic-mcp

[npm version] [License: MIT]

MCP server for TikTok organic analytics — video performance, engagement metrics, and profile insights via the TikTok Developer API.

Built for 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.

Part of The SEO Engine toolkit by Rex Jones — AI-powered SEO and social media tooling for agencies and businesses.

Why this exists

• No open-source TikTok organic MCP existed. Ads MCPs exist. Organic analytics? Nobody built one.
• Paid alternatives cost money. The commercial options require monthly subscriptions. This is free and open source.
• Your AI should see your TikTok data. Ask "how are my TikTok videos performing?" and get a real answer.

Quick start

Option 1: npx (no install)

Single account:

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

Multiple accounts:

{  "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\"}]"      }    }  }}

Option 2: Clone and build

git clone https://github.com/lanternrow/tiktok-organic-mcp.gitcd tiktok-organic-mcpnpm installnpm run build

Then add to your Claude Code MCP settings:

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

Getting your TikTok Access Token

Step 1: Create a TikTok Developer App

1. Go to the TikTok Developer Portal and log in
2. Click Manage apps → Connect an app
3. Fill in your app details and submit for review

Step 2: Add Login Kit and request scopes

1. In your app dashboard, add the Login Kit product
2. Request these scopes:
   • user.info.basic — profile name, avatar
   • user.info.profile — bio, verification status
   • user.info.stats — follower/following counts, total likes
   • video.list — access to video listing and metrics

Step 3: Complete the OAuth flow

1. Direct users to TikTok's authorization 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. Exchange the authorization code for tokens:
   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. Save the access_token and refresh_token from the response

Tip: Access tokens expire after 24 hours. Use the refresh_token tool or set TIKTOK_REFRESH_TOKEN to enable automatic renewal.

Multi-account support

Monitor multiple TikTok accounts from a single MCP server. Set the TIKTOK_ACCOUNTS environment variable as a JSON array:

[  {    "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"  }]

Each account object requires:

• name — a unique label you pick (used in tool calls)
• access_token — the OAuth access token

Optional:

• client_key — needed for token refresh
• refresh_token — needed for token refresh

Using accounts in tools: Every tool accepts an optional account parameter. If omitted, the first account in the array is used as default.

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

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".

Tools

Account tools

Read tools

Utility tools

All read and utility tools accept an optional account parameter to target a specific account.

Architecture

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

• Zero external HTTP dependencies — uses Node 18+ native fetch
• Multi-account support — monitor multiple TikTok accounts from one server
• Backward compatible — single-token env var still works
• Cursor-based pagination — video listing supports pagination via cursor
• Zod validation — all tool inputs validated with descriptive error messages
• Batch video queries — get details for up to 20 videos in one request

Environment variables

Multi-account (recommended)

Single account (legacy)

Development

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

Contributing

Issues and PRs welcome. If TikTok changes their API, please open an issue.

License

MIT — see LICENSE.

Built as part of The SEO Engine by Rex Jones.