threads-mcp

Threads API용 MCP 서버입니다. 플랫폼 I/O만 수하며 그 외에는 아무것도 하지 않습니다: 게시물 게시, 자신의 게시물 읽기, 해당 인사이트 읽기, 게시 한도 확인. 편집 로직도, 스케줄링도, 무엇을 써야 하는지에 대한 의견도 없습니다.

에이전트가 Threads에 도달하기 위해 필요한 조각입니다. 무엇을 게시할지는 당신의 문제입니다.

npx -y @andreaselmi/threads-mcp    # needs THREADS_ACCESS_TOKEN in the environment

• 빠른 시작

• 도구

• 액세스 토큐 받기

• 클라이언트에 연결

• 문제 해결

• 의도적으로 하지 않는 일

• 개발

빠른 시작

Node 20 이상이 필합니다. 아무것도 설치할 필요가 없습니다: MCP 클라이언트는 npx로 서버를 실행하며, 처음 사용할 때 이를 가져옵니다.

1. 장기 액세스 토큰을 받으세요 — 아래 전체 과정. 이것이 유일하게 정말 까다로운 부분이며, 이건 Meta의 잘못이지 이 패키지의 잘못이 아닙니다.

2. MCP 클라이언트를 시작하는 셸에서 내보내세요:

export THREADS_ACCESS_TOKEN="THQ..."

3. 클라이언트의 MCP 설정에 서버를 추가하세요:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"]
    }
  }
}

4. 클라이언트를 재시작하고 자신이 누구인지 물어보세요. threads_whoami를 호출하고 사용자 이름으로 답해야 합니다.

클라이언트를 전혀 개입시키기 전에 서버가 작동하는지 확인하려면:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y @andreaselmi/threads-mcp

threads-mcp라는 이름의 JSON 줄이 나오면 서버가 시작되어 토큰을 읽었다는 뜻입니다. stderr의 오류 메시지가 무엇이 누락되었는지 알려줍니다.

Related MCP server: meta-threads-mcp

도구

두 개의 게시 도구는 destructiveHint: true로 표시됩니다. 나머지는 모두 readOnlyHint입니다. 파괴적 도구 전에 확인을 요청하는 클라이언트는 이 도구들에 대해서도 확인을 요청하며, 그래야 합니다: 게시된 게시물은 즉시 공개되며 API가 편집하거나 삭제할 수 없습니다. 삭제하려면 Threads 앱을 열어야 합니다.

threads_post_insights는 자신의 게시물에 대한 인사이트만 읽으며 threads_manage_insights 범위가 필요합니다. threads_publishing_limit는 24시간 이동 할당량을 보고하며, 기본적으로 계정당 250개 게시물입니다.

threads_publish_container가 존재하는 이유

Threads에서 게시는 두 번의 호출로 이루어집니다: 컨테이너를 만든 다음 그것을 게시합니다. 두 번째 호출이 실패하면 컨테이너는 여전히 존재하며 24시간 동안 유효합니다 — 전체 작업을 재시도하면 같은 텍스트가 두 번 게시됩니다. 게시가 실패하면 이 서버는 오류 메시지에 컨테이너 id를 넣습니다. 그 id를 threads_publish_container에 전달하면 작업을 정확히 한 번 완료할 수 있습니다.

또한 서버는 게시 전에 컨테이너가 FINISHED에 도달할 때까지 기다리며, 최대 1분 동안 2초 간격으로 폴링하므로 느린 컨테이너를 실패로 오인하지 않습니다.

액세스 토큰 받기

Meta의 절차는 네 단계이며 지름길이 없습니다. 처음에는 15분을 예상하세요.

1. 앱 만들기

developers.facebook.com/apps로 이동하여 Threads 사용 사례로 앱을 만드세요. 대시보드는 두 세트의 자격 증명을 생성합니다 — Facebook 것이 아닌 Threads 전용 앱 ID와 secret을 사용하세요. 이 부분에서 거의 모든 사람이 실수합니다.

2. 범위와 테스터 추가

Threads 사용 사례에서 필요한 범위를 추가하세요:

그런 다음 Threads 계정을 테스터로 추가하고 해당 계정의 설정에서 초대를 수락하세요 (Account → Website permissions → Invites). 초대가 수락될 때까지 모든 호출은 초대를 언급하지 않는 권한 오류로 실패합니다.

3. 단기 토큰 받기

브라우저에서 자리 표시자를 교체하여 인증 창을 여세요:

https://threads.net/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code

승인하면 ?code=...가 추가된 redirect_uri로 이동합니다. 리다이렉트 URI는 앱 설정에 등록된 것과 정확히 일치해야 합니다. 코드를 복사하세요 — 1회용이며 몇 분 후 만료됩니다 — 그리고 교환하세요:

curl -X POST https://graph.threads.net/oauth/access_token \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=THE_CODE_FROM_THE_REDIRECT

이것은 1시간 동안 유효한 단기 토큰을 반환합니다. 여기서 멈추지 마세요.

4. 장기 토큰으로 교환

curl -G https://graph.threads.net/access_token \
  -d grant_type=th_exchange_token \
  -d client_secret=YOUR_APP_SECRET \
  -d access_token=THE_SHORT_LIVED_TOKEN

결과는 60일 동안 유효합니다. 이것이 THREADS_ACCESS_TOKEN의 값입니다.

토큰 유지하기

장기 토큰은 발급된 지 최소 24시간이 지난 후, 만료되기 전에 한 번 갱신할 수 있습니다. 갱신할 때마다 60일이 추가됩니다:

curl -G https://graph.threads.net/refresh_access_token \
  -d grant_type=th_refresh_token \
  -d access_token=YOUR_LONG_LIVED_TOKEN

60일 동안 사용되지 않은 토큰은 만료되어 갱신할 수 없습니다 — 3단계부터 다시 시작해야 합니다. 달력에 알림을 설정하세요; 아무것도 경고하지 않습니다.

클라이언트에 연결

환경 변수

토큰은 시작 시 환경에서 읽히며 어디에도 기록되지 않습니다 — 파일에도, 로그 줄에도 기록되지 않습니다. 구성 파일에 작성하는 것보다 셸에서 내보내는 것을 선호하세요: 구성 파일은 커밋되지만 셸 내보내기는 그렇지 않습니다.

Claude Code

claude mcp add threads --scope user -- npx -y @andreaselmi/threads-mcp

또는 프로젝트 루트에 .mcp.json을 커밋하여 그 프로젝트에서 작업하는 모든 사람이 서버를 사용할 수 있게 하세요:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp@^0.1.0"]
    }
  }
}

^0.1.0으로 고정하면 수정 사항은 적용되지만 도구를 변경하는 향후 주요 버전은 적용되지 않습니다. /mcp로 연결을 확인하세요.

Claude Desktop, Cursor 및 기타 클라이언트

같은 형식으로 해당 클라이언트의 구성 파일에 넣습니다 — Claude Desktop은 claude_desktop_config.json, Cursor는 ~/.cursor/mcp.json. 셸 환경을 상속하지 않는 클라이언트는 토큰을 명시적으로 전달해야 합니다:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"],
      "env": { "THREADS_ACCESS_TOKEN": "THQ..." }
    }
  }
}

이렇게 하면 그 파일에 실제 자격 증명이 저장됩니다: 버전 관리에서 제외하세요.

대신 설치하기

매번 시작할 때 npx를 거치고 싶지 않다면:

npm install -g @andreaselmi/threads-mcp

그런 다음 args 없이 "command": "threads-mcp"를 사용하세요.

문제 해결

서버가 시작되지 않거나 클라이언트에 CONNECTION_CLOSED가 표시됩니다. 프로세스가 시작 시 종료되었습니다. 거의 항상 클라이언트가 실행된 환경에 THREADS_ACCESS_TOKEN이 설정되지 않았기 때문입니다. 터미널에서 내보내는 것은 이미 실행 중인 앱이나 Dock에서 시작한 앱에는 적용되지 않습니다. 실제 메시지를 보려면 서버를 직접 실행하세요:

npx -y @andreaselmi/threads-mcp

서버는 이유를 출력하고 종료합니다.

Invalid OAuth access token 또는 유사한 오류. 토큰이 만료되었거나(60일) 아직 3단계의 단기 토큰을 사용 중입니다. 4단계를 다시 수행하세요.

작동해야 하는 호출에서 권한 오류. 범위가 누락되었거나 — 인사이트와 게시에는 각각 해당 범위가 필요합니다 — 테스터 초대가 Threads 계정 설정에서 수락되지 않았습니다.

Post is N characters, the Threads limit is 500. 이 서버가 요청을 보내기 전에 발생시키므로 아무것도 게시되지 않았습니다. 텍스트를 나누세요.

게시가 실패했는데 실제로 나갔는지 확실하지 않습니다. 오류를 읽어보세요: 컨테이너 id를 언급하면 컨테이너가 존재하며 게시물은 나가지 않은 것입니다. 다시 게시하는 대신 해당 id로 threads_publish_container를 호출하세요. id를 언급하지 않으면 재시도 전에 threads_list_posts를 확인하세요.

할당량 소진. threads_publishing_limit는 24시간 이동 창을 보여줍니다 — 계정당 250개 게시물. 할당량을 모두 사용하면 게시물이 창에서 벗어날 때까지 아무것도 게시되지 않습니다.

의도적으로 하지 않는 일

텍스트 게시물만 지원합니다 — 이미지, 비디오, 캐러셀 또는 링크 첨부는 없습니다. 자신의 게시물만 읽으며 답글, 멘션 또는 다른 사람의 콘텐츠는 읽지 않습니다. 스케줄링, 타이머 재시도, 호출 간 상태 유지를 하지 않습니다: 데이터베이스를 보유하지 않으며 아무것도 기억하지 않습니다.

또한 무엇을 게시하는지에 대해서는 전혀 알지 못합니다. 여기에는 테마, 어조, 편집 규칙이 없습니다; 그것은 호출하는 쪽의 몫입니다. 제품별 동작을 추가하는 풀 리퀘스트는 그 동작을 호출자로 옮기도록 요청받을 것입니다.

개발

npm install
npm test          # vitest, no network: fetch is stubbed
npm run dev       # run the server from source over stdio
npm run build     # tsc to dist/

모든 테스트는 가짜 fetch로 실행되므로 테스트 스위트는 실제 API에 접촉하지 않으며 토큰이 필요 없습니다. 이슈와 풀 리퀘스트: github.com/andreaselmi/threads-mcp.

라이선스

MIT