tiktok-insights

TikTok Insights

Fetch transcripts, post metadata, and search results from TikTok via the TikNeuron MCP API.

When this skill activates

• User shares a TikTok URL and asks for a transcript, summary, stats, or virality analysis
• User wants to search TikTok for a topic
• User asks for post metadata (creator, hashtags, views, likes, duration)
• User wants to "chat with" a TikTok video (skill fetches subtitle + details, then you reason over them)

Prerequisites

The user needs a TikNeuron MCP API key (free tier = 20 credits/month). Each skill call = 1 credit.

• Sign up: https://tikneuron.com/tools/tiktok-mcp
• Pricing: Free 20/mo · Pro $7.49 / 500 · Business $24 / 1,800

The key must be available to the skill via one of:

1. Environment variable TIKNEURON_MCP_API_KEY (preferred)
2. Passed inline by the user in the conversation

On first use, check for the env var. If missing, ask the user once for the key and remember it for the session.

The three operations

This skill is a thin, faithful port of the upstream MCP server. There are exactly three operations — no more, no less. Don't invent extras.

Operation	When to use	Credits
get_subtitle	User wants the transcript, captions, or spoken content of a single video	1
get_post_details	User wants stats, metadata, creator, hashtags, engagement for a single video	1
search	User wants to discover videos matching a keyword/topic	1 per page

Workflow

User request
   │
   ├─ Contains a tiktok.com / vm.tiktok.com URL?
   │     ├─ Wants transcript/subtitle/content ──▶ get_subtitle
   │     ├─ Wants stats/metadata/virality     ──▶ get_post_details
   │     └─ Wants "why did this go viral"     ──▶ get_post_details + get_subtitle
   │
   └─ No URL, topic keyword                    ──▶ search
            └─ User wants more pages           ──▶ search (feed back cursor + search_uid)

How to call the API

Use the helper script at scripts/tiktok_call.sh. It handles auth, JSON bodies, and errors for all three endpoints.

# Subtitle (ASR fallback when language_code omitted)
scripts/tiktok_call.sh subtitle "https://www.tiktok.com/@user/video/1234567890" [language_code]

# Post details
scripts/tiktok_call.sh details "https://www.tiktok.com/@user/video/1234567890"

# Search (first page)
scripts/tiktok_call.sh search "Formula 1 crashes"

# Search (next page — pass cursor and search_uid from previous response)
scripts/tiktok_call.sh search "Formula 1 crashes" <cursor> <search_uid>

If the shell helper is unavailable, fall back to a direct curl (see references/api-reference.md for the full spec).

Credit management

Every call costs 1 credit. The free tier is 20/month — burn rate matters.

• Before chaining operations, tell the user what it will cost. Example: "To analyze virality I need to fetch post details (1 credit) and the transcript (1 credit) — 2 credits total. Proceed?"
• Never loop search to exhaustion. Return one page, summarize, and ask if the user wants the next page.
• For "analyze this TikTok" requests, default to get_post_details first. Only fetch the subtitle if the user's question actually needs the spoken content.

Input handling

TikTok URL forms

The tiktok_url parameter accepts:

• Standard: https://www.tiktok.com/@creator/video/1234567890123456789
• Short: https://vm.tiktok.com/ZMabcdefg/
• Raw video ID: 1234567890123456789

Don't "fix" or re-encode URLs — pass them verbatim.

Language codes (subtitle only)

language_code is optional. Omit it to get auto-ASR (automatic speech recognition). Pass an ISO code like en, es, fr, de, ja, ko when the user wants a specific uploaded/translated caption track.

If unsure which languages a video has: call get_post_details first — the response lists Available subtitles.

Output parsing

TikNeuron returns human-readable prose, not structured JSON. Fields are labeled line-by-line. When presenting results to the user:

• Subtitles: Return the raw transcript text. Offer to summarize it as a follow-up, don't force a summary.
• Post details: Reformat the labeled lines into a clean bullet list. Preserve exact numbers (don't round views/likes).
• Search: Show results as a numbered list with creator, description, engagement snapshot, and URL. Always surface the cursor and search_uid at the end for pagination — these are opaque tokens; never parse or modify them.

Virality analysis pattern

When the user asks "why did this go viral" or similar:

1. Call get_post_details → capture views, likes, shares, comments, hashtags, duration, creation date
2. Call get_subtitle → capture spoken content
3. Reason over both: hook strength (first 3 seconds), pacing, trend alignment (hashtags), emotional triggers, CTA, duration vs engagement ratio
4. Present a short verdict + concrete factors, not a generic checklist

Tool usage (cascading fallback)

The skill's own data fetch:

1. Preferred: scripts/tiktok_call.sh (shell script with curl, in this skill)
2. Fallback: Direct curl via Bash, using endpoint specs in references/api-reference.md
3. Last resort: Ask the user to paste the raw JSON/text response from TikNeuron's web playground

For rendering results:

1. Preferred: Inline markdown in the chat (bullets, tables, numbered lists)
2. Optional: If the user wants it saved, write to a file they specify

Honest limitations

This skill can do exactly what TikNeuron's MCP API does — and nothing more:

• Read-only. No uploading, posting, commenting, liking, or following.
• Per-video only. No user-profile endpoints, no follower data, no FYP feed.
• No trend analytics. For hashtag time-series or growth rate, use a different service (trendsmcp).
• No ads / monetization data. Use the official TikTok Business API for that.
• No comment bodies. Engagement counts are available; comment text is not.
• No video/audio download. Text-only responses.
• Credit-gated. Free tier caps at 20 calls/month. Be frugal.
• Third-party dependence. If TikNeuron is down or changes its response shape, this skill breaks with it.

Edge cases

• No API key: Ask the user once. Show the signup URL: https://tikneuron.com/tools/tiktok-mcp
• Private / removed video: TikNeuron returns an error. Surface the HTTP status and message verbatim; don't retry.
• Rate limit / credit exhausted: Tell the user they've hit the cap and link pricing.
• Shortened URL doesn't resolve: Try passing it through anyway — TikNeuron resolves vm.tiktok.com links server-side.
• Non-TikTok URL: Refuse gently. This skill only handles TikTok.

Output format (when presenting to user)

Post details:

**@creator** · posted 2026-03-12 · 42s
📝 "Original description text"

📊 Stats
- 2,450,000 views
- 312,000 likes
- 18,400 comments
- 9,200 shares
- 45,000 bookmarks

🏷 Hashtags: #fyp #viral #cooking
🗣 Available subtitles: en, es, auto-asr
🔗 Video ID: 7xxxxxxxxxxxxxxxxxx

Search results:

1. **@creator1** — "Description..." · 1.2M views · [url]
2. **@creator2** — "Description..." · 840K views · [url]
...
(next page: pass cursor=`...` and search_uid=`...`)

Subtitle: return as a clean monospace/quote block so the user can copy it.