6551Team/opentwitter-mcp

opentwitter-mcp – AI 어시스턴트를 위한 Twitter 데이터 서버

개요 – FastMCP 기반의 소규모 HTTP/WebSocket 서버로, Twitter/X 데이터(프로필, 트윗, 검색, 팔로워 이벤트, KOL 트래킹 등)를 간단한 API로 래핑합니다. 이 서버는 로컬에서 실행한 후 Claude, OpenClaw, Cursor, Zed 등과 같은 AI 기반 코딩 어시스턴트에 MCP (Model-Context-Protocol) 서버로 추가하여, 어시스턴트가 Twitter에 대해 자연어로 질문하고 구조화된 결과를 얻을 수 있도록 설계되었습니다.

주요 기능

기능	노출 방식
사용자 프로필 조회	get_twitter_user / get_twitter_user_by_id
사용자의 최근 트윗	get_twitter_user_tweets
키워드 / 해시태그 검색	search_twitter, search_twitter_advanced
실시간 팔로워 / 언팔로우 이벤트	get_twitter_follower_events (WebSocket push)
삭제된 트윗 감지	get_twitter_deleted_tweets
KOL-팔로워 발견	get_twitter_kol_followers
관심 목록 관리 (추가 / 삭제 / 목록)	add_twitter_watch, delete_twitter_watch, get_twitter_watch
전체 트윗 가져오기 (답글, 인용, 미디어 포함)	get_twitter_tweet_by_id, get_twitter_quote_tweets_by_id, get_twitter_retweet_users_by_id

설치 및 시작하기

1. 토큰 획득 – http://app.newsliquid.com/mcp에서 등록하고 OPENNEWS_TOKEN을 복사합니다.
2. 토큰 설정 – 환경 변수로 설정하거나 프로젝트 루트의 config.json에 배치합니다:

   export OPENNEWS_TOKEN="<your-token>"   # macOS / Linux
   # Windows PowerShell
   $env:OPENNEWS_TOKEN = "<your-token>"
   

3. 서버 실행 – README는 uv 빌드 도구 (Poetry/venv의 현대적인 Python-only 대안)를 권장합니다:

   uv --directory /path/to/twitter-mcp run twitter-mcp
   

   동일한 명령어를 지원되는 AI 클라이언트 (Claude Code, OpenClaw, Cursor, etc.)의 MCP 설정에 포함할 수 있습니다.

AI 어시스턴트가 통신하는 방식

• 어시스턴트는 서버를 twitter라는 이름의 MCP로 등록합니다.
• 사용자가 자연어 요청 (예: “@elonmusk의 Twitter 프로필을 보여줘” )을 입력하면, 어시스턴트는 적절한 도구 (예: get_twitter_user)를 호출합니다.
• 결과는 README에 정의된 JSON 구조로 반환됩니다 (사용자 객체, 트윗 객체, 이벤트 배열, 등).
• 실시간 모니터링을 위해, 어시스턴트는 WebSocket wss://ai.6551.io/open/twitter_wss?token=YOUR_TOKEN을 열고 NEW_TWEET, NEW_FOLLOWER, DELETE, 등과 같은 JSON-RPC push 이벤트를 받습니다.

설정 옵션

변수	용도
OPENNEWS_TOKEN (필수)	6551 백엔드 API의 Bearer token
TWITTER_API_BASE	기본 REST 엔드포인트 재정의 (기본값 https://ai.6551.io)
TWITTER_MAX_ROWS	요청당 반환되는 최대 항목 수 (기본값 100)

환경 변수와 config.json 파일 모두 지원됩니다; 환경 변수가 둘 다 있을 경우 환경 변수가 우선합니다.

지원되는 클라이언트 – README에는 Claude Code (claude mcp add twitter …) 및 OpenClaw (skill directory를 복사)를 위한 준비된 한 줄 명령어가 있습니다. 또한 많은 에디터 (Cursor, Zed, Continue.dev, etc.)를 위한 JSON/YAML 스니펫을 제공하여 서버를 에디터의 MCP 통합 기능에서 자동으로 실행할 수 있습니다.

개발

• 코드는 src/twitter_mcp/ 아래에 있으며, 명확한 레이아웃을 가합니다: server.py (진입점), app.py (FastMCP app), config.py, api_client.py, tools.py (8개의 공개 도구).
• 의존성 관계는 최소한입니다: mcp 프레임워크, httpx를 위한 HTTP 호출, uv를 위한 환경 관리.
• 프로젝트 작업: uv sync로 설치하고, uv run twitter-mcp로 실행합니다.

License – MIT, 따라서 자유롭게 수정하거나 자신의 AI-assistant 설정에 포함할 수 있습니다.

---

결론 – opentwitter-mcp는 AI 코딩 어시스턴트가 Twitter API를 직접 구현할 필요 없이 실시간 Twitter 데이터와 이벤트 스트림을 쿼리하고 받을 수 있게 해주는 가벼운 브릿지입니다. 이는 단순한 튜토리얼이나 링크 목록이 아닌, AI-augmented workflow를 위한 진정한 소프트웨어 프로젝트입니다.