TikTok MCP Server

호스팅형 Model Context Protocol(MCP) 서버로, Claude, Cursor, Windsurf 및 기타 모든 MCP 클라이언트에 읽기 전용 TikTok 도구 네 가지를 제공합니다. 공개 프로필을 조회하고, 계정의 동영상을 페이지 단위로 훑어보고, 동영상의 댓글을 읽고, TikTok에서 동영상이나 크리에이터를 검색할 수 있으며, 모든 결과는 구조화된 JSON으로 반환됩니다. TikTok 개발자 계정도 OAuth도 필요하지 않습니다.

로그아웃한 방문자가 볼 수 있는 공개 데이터만 읽습니다. 로그인하거나 게시하거나 계정으로 동작하지 않습니다.

https://mcp.hasdata.com/api/mcp?apis=tiktok

목차

• 필요한 것

• 빠른 시작

• 예제 프롬프트

• 도구

• 오류 및 실패 경로

• 요금, 무료 티어 및 제한

• 도구 선택

• 비교

• FAQ

• HasData 링크

• 개발

• 기여

• 라이선스

Related MCP server: tiktok-mcp

필요한 것

MCP 클라이언트와 대시보드에서 무료로 만들 수 있는 HasData API 키가 필요합니다. 이 서버는 원격 서버이므로 가장 간단한 방법은 URL과 x-api-key 헤더를 사용하는 것입니다. 실행할 컨테이너가 없고 전체 과정 어디에도 TikTok 개발자 계정이 필요하지 않습니다. stdio만 지원하는 클라이언트는 npm에 @hasdata/tiktok-mcp로, PyPI에 hasdata-tiktok-mcp로 배포된 가벼운 런처를 통해 접속합니다. 이는 아래에서 설명합니다.

빠른 시작

서버 URL은 모든 클라이언트에서 동일합니다. 우리는 Claude Code와 Claude Desktop에서 직접 실행해 보았습니다. 나머지 섹션은 각 클라이언트가 원격 서버용으로 문서화한 형식을 따릅니다.

OAuth를 지원하는 클라이언트는 동일한 URL을 커넥터로 추가하고 설정 파일에 키를 넣지 않고도 로그인할 수 있습니다.

claude mcp add --transport http tiktok "https://mcp.hasdata.com/api/mcp?apis=tiktok" \
  --header "x-api-key: HASDATA_API_KEY"

설정에서 커넥터로 이동한 뒤, 사용자 지정 커넥터 추가를 선택하고 https://mcp.hasdata.com/api/mcp?apis=tiktok을 붙여넣은 다음 로그인합니다.

설정 파일을 사용하는 경우, Claude Desktop은 로컬(stdio) 서버만 불러오므로 stdio 런처를 통해 원격 서버에 접속합니다. @hasdata/tiktok-mcp 패키지가 바로 그 런처이며, 키를 환경 변수에서 읽습니다. claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "tiktok": {
      "command": "npx",
      "args": ["-y", "@hasdata/tiktok-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Node 대신에 Python을 사용하시나요? 런처를 PyPI 패키지로 바꾸세요. uvx가 수동 설치 없이 실행합니다:

{
  "mcpServers": {
    "tiktok": {
      "command": "uvx",
      "args": ["hasdata-tiktok-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

모든 프로젝트에 적용하려면 ~/.cursor/mcp.json에, 한 프로젝트에만 적용하려면 .cursor/mcp.json에 넣습니다:

{
  "mcpServers": {
    "tiktok": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json에 넣습니다. Windsurf는 필드 이름을 url이 아니라 serverUrl로 사용합니다:

{
  "mcpServers": {
    "tiktok": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "tiktok": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

작업 공간의 .vscode/mcp.json에 넣습니다:

{
  "servers": {
    "tiktok": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.codex/config.toml에 넣습니다:

[mcp_servers.tiktok]
url = "https://mcp.hasdata.com/api/mcp?apis=tiktok"

[mcp_servers.tiktok.headers]
"x-api-key" = "HASDATA_API_KEY"

~/.gemini/settings.json에 넣습니다:

{
  "mcpServers": {
    "tiktok": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

예제 프롬프트

프롬프트이지 코드가 아닙니다. 하나를 붙여넣으면 에이전트가 도구를 스스로 선택합니다. 각각 필요한 호출 수가 함께 표시되어 있습니다. MCP에서는 모델이 호출 횟수를 결정하고, 성공한 호출마다 10크레딧이 소모되기 때문입니다.

@mrbeast를 대상으로 삼아. 프로필을 가져오고, 동영상의 처음 두 페이지를 돌며 그 동영상들의 조회수 중앙값을 알려줘.

세 번의 호출, 30크레딧. 프로필이 한 번, 동영상 페이지 각각이 한 번씩입니다.

"콜드브루 커피"와 관련해 크리에이터를 검색하고, 팔로워 수 기준 상위 10명을 각각의 소개와 함께 나열해줘.

한 번의 호출, 10크레딧. 사용자 검색 결과에는 이미 팔로워 수와 소개가 포함되어 있으므로 프로필마다 추가로 조회할 필요가 없습니다.

여기 동영상 URL이 하나 있습니다. 상위 댓글을 읽고 전반적인 반응과 가장 좋아요를 많이 받은 답글 세 개를 알려줘.

한 번의 호출, 10크레딧. URL에 있는 숫자 id만 있으면 댓글 도구가 작동합니다.

그 동일한 동영상에 대해, 가장 많이 좋아요를 받은 댓글 아래의 답글들을 펼쳐 보여줘.

두 번의 호출, 20크레딧. 먼저 최상위 댓글을 가져온 뒤, 그 댓글의 id로 답글을 조회하는 두 번째 호출이 필요합니다.

"asmr" 동영상을 검색하고, 조회수가 가장 높은 세 동영상의 작성자 프로필을 가져와.

네 번의 호출, 40크레딧. 검색 한 번, 작성자마다 프로필 한 번씩입니다. 검색 결과의 모든 작성자에는 프로필 엔드포인트로 직접 연결되는 링크가 있으므로 에이전트가 핸들을 추측할 필요가 없습니다.

페이지 이동은 호출할 때마다 비용이 듭니다. 프로필을 조회한 뒤 동영상 다섯 페이지를 순회하는 크리에이터 감사는 여섯 번의 호출, 60크레딧이 소모됩니다. 무료 체험은 끝이 없는 크롤링보다는 질문을 좁힐 때 더 오래 쓸 수 있습니다.

도구

네 가지 도구로, 모두 읽기 전용입니다. 아래 샘플은 실제 호출에서 일부를 발췌한 것이며 숫자는 TikTok이 업데이트되면 바뀝니다. 형태만 참고하세요. 각 도구 이름은 전체 필드 목록이 담긴 엔드포인트 문서로 연결됩니다.

샘플은 페이로드(payload)일 뿐 전체 응답이 아닙니다. tools/call 결과에는 텍스트 블록 하나가 들어 있고, 그 텍스트 자체가 url, status, text, json을 담은 JSON이며, 스크래핑한 데이터는 json 안에 있습니다. 원시 JSON-RPC 응답에서 경로는 result.content[0].text를 파싱하면 .json으로 이어집니다. 채팅 클라이언트는 그 경로를 풀어서 보여주지만, 엔드포인트에 직접 맞서는 코드는 그렇지 않습니다.

핸들, 동영상 id, 댓글 id는 서로 이어집니다. 프로필은 자신의 게시물로 연결되고, 각 포스트에는 댓글 도구용 자체 동영상 id가 있으며, 댓글과 검색 결과의 모든 작성자에는 자신의 프로필로의 hasdataLink와 자신의 동영상으로의 hasdataPostsLink가 있습니다. 에이전트는 키워드 → 크리에이터 → 동영상 → 댓글로 이동하며 URL을 직접 만들 필요가 없습니다.

Get TikTok profile

hasdata_tiktok_profile_getTikTokProfile

하나의 공개 계정을 핸들로 조회합니다.

username, nickname, biography, bioLink, verified, language, createTime, 아바타 URL, 그리고 followers, follows, likes, videos, friends 개수를 정수로 반환합니다. 개수는 이미 파싱되어 있으므로, followers > 1000000은 표시용 문자열이 아닌 실제 숫자를 비교합니다.

존재하지 않는 핸들을 조회해도 requestMetadata.status는 여전히 ok로 오며, profile 객체만 없습니다. username이나 다른 필드를 읽기 전에 객체가 있는지 먼저 확인하세요. 그렇지 않고 profile.username을 수행하는 에이전트는 아무것도 없는 객체를 읽다가 예외를 던집니다.

{
  "username": "mrbeast",
  "nickname": "MrBeast",
  "verified": true,
  "biography": "Checkout My New Book!👇",
  "bioLink": "http://themostdangerousgames.com",
  "createTime": "2018-10-20T19:26:16.000Z",
  "followers": 138387571,
  "follows": 354,
  "likes": 1427086888,
  "videos": 466,
  "friends": 285
}

hasdata_tiktok_posts_getTikTokPosts

hasdata_tiktok_posts_getTikTokPosts TwoClick ...

계정의 동영상 목록을 핸들로 조회하며, 최신순으로 페이지 단위로 반환합니다.

한 번 호출하면 동영상 약 30개와 pagination이 반환됩니다. pagination에는 hasMoreChat와 다음 페이지로 넘기기 위해 다시 넣는 nextPageToken이 있습니다. 각 동영상은 id, description, url, duration, 커버 및 재생 가능한 동영상 URL, music, 그리고 정수로 된 likes, comments, shares, plays, collects, reposts 개수를 담고 있습니다.

hashtags와 mentions는 해당 기능을 사용한 동영상에만 존재합니다. 실제 한 페이지 데이터(27개 동영상)에서 hashtags 배열은 4개, mentions는 10개였습니다. 모든 동영상에 이 두 키가 모두 있다고 가정하지 말고, 읽기 전에 키가 있는지 먼저 확인하세요.

{
  "id": "7677375185028271391",
  "description": "would you take the car or nah?",
  "url": "https://www.tiktok.com/@mrbeast/video/7677375185028271391",
  "createTime": "2026-08-23T23:36:59.000Z",
  "duration": 41,
  "likes": 129500,
  "comments": 6670,
  "shares": 2033,
  "plays": 1100000,
  "collects": 4986,
  "music": { "title": "original sound", "authorName": "MrBeast", "original": true }
}

hasdata_tiktok_comments_getTikTokComments

hasdata_tikTokComments

공개 동영상의 댓글 또는 특정 댓글 아래의 답글을 조회합니다.

각 댓글에는 text, likes, createTime, replyCount와 author가 있고, 모든 작성자에는 자신의 프로필로 연결되는 hasdataLink와 자신의 동영상으로 연결되는 hasdataPostsLink가 포함됩니다. pagination.total은 동영상의 전체 댓글 수를 알려주므로 페이지를 넘기기 전에 전체 규모를 알 수 있습니다. replyCount가 0이 아닌 댓글은 그 id를 commentId로 넣어 다시 호출하면 답글에 도달할 수 있습니다.

{
  "id": "7677377150003053325",
  "text": "How could someone turn down a car",
  "createTime": "2026-08-23T23:45:06.000Z",
  "likes": 3802,
  "replyCount": 22,
  "author": {
    "username": "hohce.verggr",
    "nickname": "Sasori",
    "hasdataLink": "https://api.hasdata.com/scrape/tiktok/profile?handle=hohce.verggr",
    "hasdataPostsLink": "https://api.hasdata.com/scrape/tiktok/posts?handle=hohce.verggr"
  }
}

hasdata_tiktok_search_getTikTokSearch

hasdata_tiktok_search_getTikTokSearch

동영상 또는 크리에이터를 키워드로 검색합니다.

type이 video이면 게시물 도구가 반환하는 것과 같은 항목으로 동영상이 각 작성자와 함께 반환됩니다. type이 user이면 각 크리에이터에 대해 username, nickname, signature(소개), avatarUrl, followers, 그리고 프로필이나 동영상으로 연쇄 조회할 수 있는 동일한 hasdataLink와 hasdataPostsLink를 반환합니다. verified 플백은 그러한 계정에만 존재합니다.

{
  "username": "la.mooncoldbrew",
  "nickname": "lamoon cold brew coffee",
  "signature": "อยากได้สูตรชงเมนูไหน Comment ไว้เลยน้า",
  "followers": 48000,
  "hasdataLink": "https://api.hasdata.com/scrape/tiktok/profile?handle=la.mooncoldbrew",
  "hasdataPostsLink": "https://api.hasdata.com/scrape/tiktok/posts?handle=la.mooncoldbrew"
}

오류 및 실패 경로

사용자의 클라이언트는 도구 호출에서 HTTP 오류 코드를 거의 보지 못합니다. MCP 레이어가 200으로 응답하고, 실패 내용을 isError가 true로 설정된 텍스트와 함께 결과 안에 넣습니다. 상태 줄을 기대할 자리에서 에이전트는 메시지를 읽습니다.

잘못된 키는 연결 실패가 아닌 도구 출력으로 드러납니다. tools/list는 비어 있지 않은 키라면 무엇이든 수락하고 네 개의 도구를 모두 반환하므로, 클라이언트는 핸드셰이크를 완료하고 정상 상태를 표시합니다. 첫 번째 도구 호출이 돌아올 때 isError: true와 텍스트 HasData API error: 401 Unauthorized가 함께 돌아옵니다. 흐름의 앞부분에서 문제를 보고하는 내용이 없으므로 이 문자열을 주의하세요.

키가 없는 경우에만 실제 HTTP 오류가 발생합니다. 인증은 모든 도구보다 먼저 실행되며 연결 자체가 401로 실패합니다. CORS 헤더가 포함되어 있으므로 브라우저 클라이언트는 불투명한 네트워크 실패가 아닌 상태 코드를 읽습니다.

도구의 스키마를 깨뜨리는 인자는 스크래핑으로 이어지기 전에 거부됩니다. 서버는 isError: true와 텍스트 MCP error -32602: Input validation error로 응답하며 위반 필드를 이름으로 알려줍니다. 아무것도 가져오지 않으며 요금도 부과되지 않습니다.

성공했지만 아무것도 찾지 못한 호출이 사람들이 헷갈리는 경우입니다. 존재하지 않는 핸들은 일반 결과로 돌아오는데 requestMetadata.status가 ok로 설정되어 있고 데이터 키가 그냥 없습니다. 본문 어디에도 결과가 비었다는 표시가 없습니다. 오류를 시험하지 말고 필요한 필드를 시험하세요.

플랫폼이 거부하는 식별자는 400을 반환하며 requestMetadata.status는 error로 설정됩니다.

데이터가 포함된 결과에는 관리 중 인용할 만한 requestMetadata.id도 함께 있습니다.

가격, 무료 등급 및 한도

모든 TikTok 도구는 성공적인 호출당 10 크레딧이 소비됩니다. 응답 크기에 따라 가격은 변하지 않습니다. 비디오가 가득 찬 페이지도 필드 하나만 있는 프로필과 비용이 같습니다.

무료 체험 기간은 카드 등록 없이 30일간 1,000 크레딧이며, 이는 TikTok 호출 100회에 해당합니다. 이후 활성 계정은 잔액이 100 아래로 내려갈 때마다 매일 100 크레딧이 채워지므로, 사용량이 적은 에이전트는 무료 등급으로 계속 운영됩니다.

유료 요금제는 월 $49부터 시작하며 200,000 크레딧, 즉 20,000회 호출입니다. 단위 가격은 규모가 커질수록 낮아져서, 시작 요금제 1,000회 호출당 $2.45, Business요금 $0.99, Growth $0.83, 가장 큰 고용량 요금제는 $0.75입니다.

요금제는 동시 실행 수도 설정합니다. 무료 체험은 한 번에 1개 요청, Startup은 15개, Business는 30개, Growth는 50개, 고용량 요금제는 200개부터 1,500개까지 허용합니다. 무인 환경에서도 오버플로 상황을 방어적으로 처리하세요. 에이전트가 요청을 확산하면 먼저 한도에 도달합니다.

비해 200이 아닌 요청은 청구되지 않습니다. 아무것도 찾지 못해도 성공한 호출은 여전히 호출입니다.

도구 선택

apis 쿼리 매개변수가 에이전트가 보는 도구를 결정합니다. 도구가 적으면 도구 정의에 사용되는 컨텍스트도 줄고, 모델이 잘못된 도구를 선택할 가능성도 낮습니다.

?apis=tiktok                     the four tools in this repo
?apis=tiktok,instagram           a social bundle
?apis=tiktok,google_serp         add Google search

이 매개변수는 tiktok 같은 공급자 이름과 tiktok_search 같은 개별 API 이름을 받습니다. 철자가 틀린 이름은 무시됩니다. 모든 이름이 틀리면 요청이 400으로 실패하고, 응답 본문에는 그것이 인식하지 못한 이름과 모든 유효한 값을 목록으로 열거합니다. 매개변수를 제거하면 같은 엔드포인트가 HasData 도구 57개를 모두 노출합니다.

다른 방법과의 비교

TikTok 자체 개발자 프로그램은 공개 콘텐츠에 대한 일반적인 읽기를 지원하지 않습니다. Research API는 애플리케이션 승인을 거쳐 제한된 지역에 있는 검증된 학술·비영리 연구자에게만 열려 있습니다. Display API는 OAuth로 로그인하는 계정의 콘텐츠만 반환합니다. 임의의 공개 프로필, 그 프로필의 비디오, 비디오의 댓글을 읽어야 하는 에이전트에는 어느 쪽도 맞지 않습니다.

대부분의 다른 TikTok MCP 서버는 비공식 단일 엔드포인트를 모아 놓습니다. 이 서버는 에이전트가 실제로 엮어 쓰는 네 가지 읽기 대상(프로필→게시물→댓글)뿐 아니라 검색까지 갖추므로, 전체 조사 과정은 하나의 서버에만 필요해 수행됩니다.

이 서버가 하지 않는 작업 posting(게시), 다이렉트 메시지, 팔로워 전용 또는 비공개 콘텐츠, 회원님이 소유하지 않은 계정의 분석은 포함되지 않습니다. 로그아웃된 방문자가 볼 수 있는 내용만 읽습니다.

FAQ

공식 TikTok MCP 서버가 있나요?

TikTok은 공식 서버를 제공하지 않습니다. 모든 서버는 제3자가 만든 것들입니다. 이 서버는 HasData가 유지 관리하며 공개 페이지를 읽기 때문에, TikTok 개발자 계정이 필요 없습니다.

TikTok MCP 서버란 무엇인가요?

AI 클라이언트가 호출할 수 있는 도구로 TikTok 데이터를 제공하는 서버입니다. 클라이언트는 Model Context Protocol로 도구 호출을 보내고, 서버는 데이터를 가져와 구조화된 JSON으로 반환하며, 모델은 결과를 사용하고 HTML 페이지는 보지 못합니다. 이 서버는 네 가지 도구를 가지며 원격으로 실행되므로, 클라이언트는 URL에 연결만 하고 로컬 프로세스를 시작하지 않습니다.

TikTok API 키나 개발자 계정이 필요한가요?

아니요. 유일한 인증 정보는 HasData 키입니다. 도구는 TikTok 개발자 API가 아니라 공개 TikTok 페이지를 읽그 때문에 제출할 개발자 애플리케이션도, OAuth 동의 화면도 없습니다.

아무것도 호스팅하거나 실행해야 하나요?

아니요. 이 서버는 스트리밍 HTTP의 원격 MCP 서버이므로 설치할 것, 유지할 컨테이너, 재시작할 프로세스가 없습니다.

데이터는 실시간인가요, 캐시인가요?

실시간입니다. 각 호출은 요청된 시점에 데이터를 가져오고 requestMetadata.id를 함께 갖습니다. 좋아요나 재생 같은 숫자는 페이지에 따라 움직이므로, 페이지의 현재 상태를 나타냅니다.

내가 아닌 개인 계정도의 비공개 계정을 읽을 수 있나요?

아니요. 로그아웃된 방문자가 볼 수 있는 것만 반환됩니다. 비공개 계정의 비디오는 공개되지 않으므로 어떤 응답에도 들어오지 않습니다.

댓글도 최상위 댓글 외에 답글도 읽을 수 있나요?

네. 댓글 도구에 commentId로 댓글의 id를 전달하면 해당 댓글에 달린 답글을 반환합니다. 댓글의 replyCount로 답글이 있는지 확인할 수 있습니다.

다른 HasData API와 함께 사용할 수 있나요?

네. apis 매개변수는 목록을 받으며 ?apis=tiktok,instagram은 네 가지 TikTok 도구와 Instagram을 모두 제공합니다. 매개변수 제거하면 모든 도구를 가져온니다.

규정 준수 및 개인 데이터

HasData는 공개적으로 얻을 수 있는 데이터만 접근합니다. 플랫폼의 이용조건이 자동 접근을 제한할 수 있으며, 규준에 대한 책임은 사용자에게 있습니다. 수집된 데이터에 개인 정보가 포함되는 경우, GDPR, CCPA 등 해당 지역에 동등한 규정에 의거한 근거가 있는지 확인하세요.

HasData 링크

개발

이 저장소는 원격 서버를 위한 설정과 문서입니다. 빌드 단계가 없고, 컨테이너화할 내용도 없다.

test/의 테스트는 도구 계약을 검증합니다. 이 계약은 이 저장소에 커밋이 없이도 깨질 수 있는 부분입니다. 테스트는 ?apis=tiktok가 정확히 네 도구를 반환하는지, 모든 도구가 여전히 필수 매개변수를 선언하는지, 이름이 바뀌지 않았는지, 사용하는 키가 절대적으로 인증을 받는지를 확인합니다. 마지막 검사는 실제 도구를 한 번 호출하며 10크레딧이 소요되는데, 이는 올바른 이유로 실패할 수 있다는 준비(카나리) 비용입니다.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

동일한 스위트 묶음은 모든 푸시와 주 1회 일변적으로 CI에서 실행됩니다. 상위 도구 목록이 이 저장소에 아무 변경 없이 바뀔 수 있기 때문입니다. 실패가 나면 도구 목록이 이동했거나, 키가 더 이상 작동하지 않거나, 엔드포인트에 연결할 수 없다는 뜻이며, 그중 무엇인지는 테스트의 주장 메시지에 나옵니다.

기여

도구 표와 응답 샘플의 수정이 가장 유용한 기여입니다. 시간이 지나면서 이 부분이 조금씩 어긋나기 때문입니다. 수행한 호출과 수신한 응답을 함께 남겨 주세요. 포크된 저장소에 PR은 키 없이도 스위핑를 실행하고, 실시간 검사는 빨간 불이 아니라 건너뛰도록 되어 있습니다.

라이선스

MIT. LICENSE를 참조하세요.