@endwaterlab/threads-mcp

v0.1.1

Published

19 days ago

Model Context Protocol server for the Meta Threads Graph API. Lets LLMs publish, read, moderate, and analyze Threads content via stdio.

0High
0Medium
0Low

leehyunjin

mcp model-context-protocol threads meta graph-api llm claude anthropic

threads-mcp

Meta Threads Graph API 를 위한 Model Context Protocol 서버. LLM 이 stdio 를 통해 본인 Threads 계정에서 게시·읽기·모더레이션·인사이트를 수행할 수 있게 합니다.

설치 및 등록

가장 간단한 방법은 npx 입니다. 장기 토큰을 준비하고 (없으면 docs/getting-started.md 참고) MCP 클라이언트에 등록하세요.

Claude Code

claude mcp add threads-mcp \
  --env THREADS_ACCESS_TOKEN=<장기 토큰> \
  -- npx -y @endwaterlab/threads-mcp

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "threads-mcp": {
      "command": "npx",
      "args": ["-y", "@endwaterlab/threads-mcp"],
      "env": {
        "THREADS_ACCESS_TOKEN": "<장기 토큰>"
      }
    }
  }
}

그 외 MCP 클라이언트

stdio 를 지원하는 모든 클라이언트에서 동작합니다:

THREADS_ACCESS_TOKEN=<token> npx -y @endwaterlab/threads-mcp

환경 변수

| 변수 | 필수 | 기본값 | 용도 | |---|---|---|---| | THREADS_ACCESS_TOKEN | 예 | — | 장기 (60일) Threads 액세스 토큰. | | THREADS_USER_ID | 아니오 (보통 비워두세요) | 첫 호출 시 /me 에서 자동 해석 | Threads 숫자 user id. username 이 아님. 잘못된 값이면 서버가 무시하고 /me 로 fallback. | | THREADS_API_BASE | 아니오 | https://graph.threads.net/v1.0 | Base URL 오버라이드 (테스트 용도). |

제공되는 도구

총 23개. Threads 엔드포인트당 도구 1개를 원칙으로 했고, 컨테이너 → 폴링 → 발행을 한 번에 처리하는 threads_post 컨비니언스 1개만 별도로 두었습니다. 전체 HTTP method, path, scope 표는 docs/endpoints.md 에 있습니다.

빠른 지도:

| 카테고리 | 도구 | |---|---| | 프로필 | threads_get_me, threads_get_user, threads_get_publishing_limit, threads_profile_lookup | | 발행 | threads_post, threads_create_container, threads_publish_container, threads_get_container_status, threads_delete_post | | 읽기 | threads_list_my_posts, threads_get_media, threads_get_conversation, threads_get_replies | | 답글 모더레이션 | threads_hide_reply, threads_list_pending_replies, threads_manage_pending_reply | | 인사이트 | threads_media_insights, threads_user_insights | | 검색 | threads_keyword_search, threads_get_mentions | | 메타 | threads_oembed, threads_debug_token, threads_refresh_access_token |

threads_post 가 가장 쉬운 경로 — media_type 과 URL / 텍스트 필드만 주면 컨테이너 생성, VIDEO 폴링, 발행을 한 번에 처리합니다. 세밀한 제어가 필요하면 threads_create_container + threads_publish_container 를 직접 사용하세요.

게시물에 답글을 달려면: threads_post 에 reply_to_id=<부모 미디어 id> 를 함께 주세요. 별도 "reply" 엔드포인트는 없고, Threads 는 답글을 부모가 있는 게시물로 취급합니다.

필요한 Threads 스코프

| Scope | 필요 시점 | |---|---| | threads_basic | 항상 | | threads_content_publish | 발행 / 삭제 | | threads_read_replies | 답글 / 멘션 읽기 | | threads_manage_replies | 답글 숨기기 / 승인 | | threads_manage_insights | 인사이트 엔드포인트 | | threads_keyword_search | 키워드 검색 (선택) | | threads_profile_discovery | 공개 프로필 조회 (선택) |

문서

docs/getting-started.md — 장기 토큰 발급 절차.
docs/endpoints.md — 전체 도구 카탈로그.
docs/architecture.md — 서버 구조 설명.
docs/research/threads-api-overview.md — Threads API 필드 정리.
docs/research/existing-mcp-servers.md — 다른 Threads MCP 들과 본 프로젝트 설계 근거.
docs/research/mcp-vs-skill.md — 언제 MCP, 언제 Skill 인가.

개발

git clone https://github.com/endwaterlab/threads-mcp
cd threads-mcp
bun install
bun run dev               # Bun 으로 ./src/index.ts 실행
bun run typecheck         # tsc --noEmit
bun run build             # tsc → dist/

# MCP Inspector 로 스모크 테스트
bunx @modelcontextprotocol/inspector node dist/index.js

배포 아티팩트에는 dist/, README.md, LICENSE 만 포함됩니다 (.npmignore 참고). npm pack --dry-run 으로 확인 가능합니다.

라이선스

MIT — LICENSE 참고.

감사 및 영향

기존 Threads MCP 생태계 조사를 바탕으로 설계 결정을 내렸습니다 (docs/research/existing-mcp-servers.md 참고).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme