X(트위터) MCP 서버

AI 도구를 통해 Twitter(X)와 상호작용하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 사용하면 AI 도구의 자연어 명령을 통해 트윗 가져오기, 게시, Twitter 검색, 팔로워 관리 등 다양한 작업을 수행할 수 있습니다.

특징

• 사용자 프로필, 팔로워, 팔로잉 목록을 가져옵니다.

• 트윗을 게시, 삭제하고 즐겨찾기에 추가하세요.

• 트윗과 트렌드를 알아보려면 Twitter를 검색하세요.

• 북마크와 타임라인을 관리합니다.

• Twitter API에 대한 내장된 속도 제한 처리.

• 적절한 인증(API 키 및 토큰)을 통해 Twitter API v2를 사용하여 사용자 이름/비밀번호 해킹을 방지하고 계정 정지 위험을 최소화합니다.

• 사용자 관리, 트윗 관리, 타임라인 및 검색 기능을 위한 Twitter API v2 엔드포인트의 완전한 구현을 제공합니다.

필수 조건

• Python 3.10 이상 : 시스템에 Python이 설치되어 있는지 확인하세요.

• Twitter 개발자 계정 : Twitter 개발자 포털 에서 API 자격 증명(API 키, API 비밀번호, 액세스 토큰, 액세스 토큰 비밀번호, Bearer 토큰)이 필요합니다.

• 선택 사항: Claude Desktop : Anthropic 웹사이트 에서 Claude Desktop 앱을 다운로드하여 설치하세요.

• 선택 사항: Node.js (MCP 통합용): Claude Desktop에서 MCP 서버를 실행하는 데 필요합니다.

• Python 종속성을 위한 uv 나 pip 와 같은 패키지 관리자.

설치

옵션 1: Smithery를 통한 설치(권장)

Smithery를 통해 Claude Desktop에 X(Twitter) MCP 서버를 자동으로 설치하려면:

지엑스피1

옵션 2: PyPI에서 설치

x-twitter-mcp 설치하는 가장 쉬운 방법은 PyPI를 사용하는 것입니다.

옵션 3: 소스에서 설치

소스 저장소에서 설치하려면 다음을 수행하세요.

1. 저장소 복제 :

   git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git cd x-twitter-mcp-server

2. 가상 환경 설정 (선택 사항이지만 권장):

   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

3. 종속성 설치 : uv 사용(프로젝트에서 uv.lock 사용하므로 권장):

   uv sync

   또는 pip 사용하면:

   pip install .

4. 환경 변수 구성 :

   • 프로젝트 루트에 .env 파일을 만듭니다(제공된 경우 .env.example 도 복사할 수 있습니다).

   • Twitter API 자격 증명을 추가하세요.

     TWITTER_API_KEY=your_api_key TWITTER_API_SECRET=your_api_secret TWITTER_ACCESS_TOKEN=your_access_token TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret TWITTER_BEARER_TOKEN=your_bearer_token

서버 실행

두 가지 방법으로 서버를 실행할 수 있습니다.

옵션 1: CLI 스크립트 사용

이 프로젝트는 CLI 스크립트 x-twitter-mcp-server 정의합니다.

PyPI에서 설치한 경우:

uv 로 소스에서 설치한 경우:

옵션 2: FastMCP 직접 사용(소스 전용)

소스에서 설치하고 FastMCP의 개발 모드를 사용하여 서버를 실행하려는 경우:

서버가 시작되고 MCP 연결을 수신합니다. 다음과 같은 출력이 표시됩니다.

Claude Desktop과 함께 사용

이 MCP 서버를 Claude Desktop과 함께 사용하려면 Claude를 서버에 연결하도록 구성해야 합니다. 다음 단계를 따르세요.

1단계: Node.js 설치

Claude Desktop은 Node.js를 사용하여 MCP 서버를 실행합니다. Node.js가 설치되어 있지 않은 경우:

• nodejs.org 에서 Node.js를 다운로드하여 설치하세요.

• 설치 확인:

  node --version

2단계: Claude Desktop 구성 찾기

Claude Desktop은 claude_desktop_config.json 파일을 사용하여 MCP 서버를 구성합니다.

• 윈도우 : %APPDATA%\Claude\claude_desktop_config.json

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

파일이 없으면 만듭니다.

3단계: MCP 서버 구성

claude_desktop_config.json 파일을 편집하여 x-twitter-mcp 서버를 포함하세요. /path/to/x-twitter-mcp-server 프로젝트 디렉터리의 실제 경로(소스에서 설치한 경우) 또는 Python 실행 파일 경로(PyPI에서 설치한 경우)로 바꾸세요.

PyPI에서 설치한 경우:

uv 로 소스에서 설치한 경우:

• "command": "x-twitter-mcp-server" : PyPI에서 설치한 경우 CLI 스크립트를 직접 사용합니다.

• "env" : PyPI에서 설치하는 경우 .env 파일이 없으므로 설정 파일에서 직접 환경 변수를 제공해야 할 수 있습니다. 소스에서 설치하는 경우 .env 파일이 사용됩니다.

• "env": {"PYTHONUNBUFFERED": "1"} : Claude에서 더 나은 로깅을 위해 출력이 버퍼링되지 않도록 보장합니다.

4단계: Claude Desktop을 다시 시작하세요

• Claude Desktop을 완전히 종료합니다.

• 새로운 구성을 로드하려면 Claude Desktop을 다시 여세요.

5단계: 연결 확인

• 클로드 데스크톱을 엽니다.

• 입력 영역(오른쪽 하단)에서 망치 또는 커넥터 아이콘을 찾으세요. 이는 MCP 도구를 사용할 수 있음을 나타냅니다.

• 아이콘을 클릭하면 x-twitter-mcp 에서 사용 가능한 도구(예: post_tweet , search_twitter , get_user_profile 등)를 볼 수 있습니다.

6단계: Claude로 테스트

이제 Claude Desktop에서 자연어를 사용하여 Twitter와 소통할 수 있습니다. 다음은 몇 가지 프롬프트 예시입니다.

• 사용자 프로필 가져오기 :

  Get the Twitter profile for user ID 123456.

  Claude는 get_user_profile 도구를 호출하고 사용자의 세부 정보를 반환합니다.

• 트윗 게시 :

  Post a tweet saying "Hello from Claude Desktop! #MCP"

  클로드는 post_tweet 도구를 사용하여 트윗을 게시하고 작업을 확인합니다.

• 트위터 검색 :

  Search Twitter for recent tweets about AI.

  클로드는 search_twitter 도구를 호출하여 관련 트윗을 반환합니다.

• 트렌드 알아보기 :

  What are the current trending topics on Twitter?

  클로드는 get_trends 도구를 사용하여 트렌드 주제를 가져옵니다.

메시지가 표시되면 Claude에게 채팅 세션에 MCP 도구를 사용할 수 있는 권한을 부여합니다.

사용 가능한 도구

아래는 x-twitter-mcp 서버에서 제공하는 모든 도구 목록과 자연어 프롬프트를 사용한 Claude Desktop의 실행 예입니다.

사용자 관리 도구

get_user_profile

• 설명 : 사용자의 자세한 프로필 정보를 얻습니다.

• 클로드 데스크톱 예 :

  Get the Twitter profile for user ID 123456789.

  클로드는 ID, 이름, 사용자 이름, 프로필 이미지 URL, 설명을 포함한 사용자 프로필 세부 정보를 반환합니다.

get_user_by_screen_name

• 설명 : 화면 이름으로 사용자를 가져옵니다.

• 클로드 데스크톱 예 :

  Get the Twitter user with screen name "example_user".

  클로드는 사용자의 프로필 세부 정보를 반환합니다.

get_user_by_id

• 설명 : ID로 사용자를 가져옵니다.

• 클로드 데스크톱 예 :

  Fetch the Twitter user with ID 987654321.

  클로드는 사용자의 프로필 세부 정보를 반환합니다.

get_user_followers

• 설명 : 지정된 사용자의 팔로워 목록을 검색합니다.

• 클로드 데스크톱 예 :

  Get the followers of user ID 123456789, limit to 50.

  클로드는 최대 50명의 팔로워 목록을 반환합니다.

get_user_following

• 설명 : 주어진 사용자가 팔로우하고 있는 사용자를 검색합니다.

• 클로드 데스크톱 예 :

  Who is user ID 123456789 following? Limit to 50 users.

  클로드는 최대 50명의 사용자 목록을 반환합니다.

get_user_followers_you_know

• 설명 : 일반적인 팔로워 목록을 검색합니다.

• 클로드 데스크톱 예 :

  Get common followers for user ID 123456789, limit to 50.

  클로드는 최대 50명의 일반 팔로워 목록을 반환합니다(팔로워 필터링을 통해 시뮬레이션).

get_user_subscriptions

• 설명 : 지정된 사용자가 구독한 사용자 목록을 검색합니다.

• 클로드 데스크톱 예 :

  Get the subscriptions for user ID 123456789, limit to 50.

  Claude는 최대 50명의 사용자 목록을 반환합니다(구독을 위한 프록시로 팔로잉을 사용).

트윗 관리 도구

post_tweet

• 설명 : 미디어, 답글, 태그를 선택하여 트윗을 게시합니다.

• 클로드 데스크톱 예 :

  Post a tweet saying "Hello from Claude Desktop! #MCP"

  클로드는 트윗을 게시하고 트윗 세부 정보를 반환합니다.

delete_tweet

• 설명 : ID로 트윗을 삭제합니다.

• 클로드 데스크톱 예 :

  Delete the tweet with ID 123456789012345678.

  클로드는 트윗을 삭제하고 작업을 확인합니다.

get_tweet_details

• 설명 : 특정 트윗에 대한 자세한 정보를 얻습니다.

• 클로드 데스크톱 예 :

  Get details for tweet ID 123456789012345678.

  클로드는 트윗의 세부 정보(ID, 텍스트, 생성 날짜, 작성자 ID 포함)를 반환합니다.

create_poll_tweet

• 설명 : 설문조사를 통해 트윗을 작성합니다.

• 클로드 데스크톱 예 :

  Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.

  클로드는 여론조사 트윗을 작성하고 트윗 세부 정보를 반환합니다.

vote_on_poll

• 설명 : 여론조사에 투표하세요.

• 클로드 데스크톱 예 :

  Vote "Blue" on the poll in tweet ID 123456789012345678.

  Claude는 모의 응답을 반환합니다(Twitter API v2는 여론조사 투표를 지원하지 않기 때문입니다).

favorite_tweet

• 설명 : 트윗을 즐겨찾기에 추가합니다.

• 클로드 데스크톱 예 :

  Like the tweet with ID 123456789012345678.

  클로드는 해당 트윗을 즐겨찾기에 추가하고 해당 작업을 확인합니다.

unfavorite_tweet

• 설명 : 트윗을 즐겨찾기에서 제외합니다.

• 클로드 데스크톱 예 :

  Unlike the tweet with ID 123456789012345678.

  클로드는 해당 트윗을 즐겨찾기에서 삭제하고 해당 작업을 확인합니다.

bookmark_tweet

• 설명 : 트윗을 북마크에 추가합니다.

• 클로드 데스크톱 예 :

  Bookmark the tweet with ID 123456789012345678.

  클로드는 트윗을 북마크하고 작업을 확인합니다.

delete_bookmark

• 설명 : 북마크에서 트윗을 제거합니다.

• 클로드 데스크톱 예 :

  Remove the bookmark for tweet ID 123456789012345678.

  클로드는 북마크를 제거하고 작업을 확인합니다.

delete_all_bookmarks

• 설명 : 모든 북마크를 삭제합니다.

• 클로드 데스크톱 예 :

  Delete all my Twitter bookmarks.

  클로드는 모든 북마크를 삭제하고 작업을 확인합니다.

타임라인 및 검색 도구

get_timeline

• 설명 : 홈 타임라인에서 트윗을 받아보세요(For You).

• 클로드 데스크톱 예 :

  Show my Twitter For You timeline, limit to 20 tweets.

  클로드는 귀하의 For You 타임라인에서 최대 20개의 트윗을 반환할 것입니다.

get_latest_timeline

• 설명 : 홈 타임라인(팔로잉)에서 트윗을 받습니다.

• 클로드 데스크톱 예 :

  Show my Twitter Following timeline, limit to 20 tweets.

  클로드는 귀하의 팔로잉 타임라인에서 최대 20개의 트윗을 반환할 것입니다.

search_twitter

• 설명 : 쿼리로 Twitter를 검색합니다.

• 클로드 데스크톱 예 :

  Search Twitter for recent tweets about AI, limit to 10.

  클로드는 AI에 대한 최근 트윗을 최대 10개까지 답글로 남겨줄 것입니다.

get_trends

• 설명 : Twitter의 트렌드 주제를 검색합니다.

• 클로드 데스크톱 예 :

  What are the current trending topics on Twitter? Limit to 10.

  클로드는 최대 10개의 인기 주제를 소개합니다.

get_highlights_tweets

• 설명 : 사용자의 타임라인에서 강조 표시된 트윗을 검색합니다.

• 클로드 데스크톱 예 :

  Get highlighted tweets from user ID 123456789, limit to 20.

  클로드는 사용자의 타임라인에서 최대 20개의 트윗을 하이라이트로 시뮬레이션하여 반환합니다.

get_user_mentions

• 설명 : 특정 사용자를 언급하는 트윗을 받습니다.

• 클로드 데스크톱 예 :

  Get tweets mentioning user ID 123456789, limit to 20.

  클로드는 해당 사용자를 언급한 트윗을 최대 20개까지 반환합니다.

문제 해결

• 서버가 시작되지 않음 :

  • .env 파일에 필요한 모든 Twitter API 자격 증명이 있는지 확인하세요(소스에서 설치한 경우).

  • PyPI에서 설치한 경우 claude_desktop_config.json 또는 셸에 환경 변수가 설정되어 있는지 확인하세요.

  • x-twitter-mcp-server 실행할 때 오류가 있는지 터미널 출력을 확인하세요.

  • uv 또는 Python 실행 파일이 올바르게 설치되고 접근 가능한지 확인하세요.

• 클로드가 서버를 감지하지 못함 :

  • claude_desktop_config.json 의 경로가 올바른지 확인하세요.

  • command 과 args 올바른 실행 파일과 스크립트를 가리키는지 확인하세요.

  • 구성 파일을 업데이트한 후 Claude Desktop을 다시 시작합니다.

  • 오류가 있는지 Claude의 개발자 모드 로그(도움말 → 개발자 모드 활성화 → MCP 로그 파일 열기)를 확인하세요.

• 속도 제한 오류 :

  • 서버에는 속도 제한 처리 기능이 포함되어 있지만 Twitter API 제한에 도달하면 재설정 창(예: 트윗 작업의 경우 15분)을 기다려야 할 수 있습니다.

• 구문 경고 :

  • Tweepy에서 SyntaxWarning 메시지가 표시된다면 Python 3.13에서 Tweepy의 docstring 문제로 인한 것입니다. 서버에는 이 문제를 해결하기 위한 경고 억제 기능이 포함되어 있습니다.

기여하다

기여를 환영합니다! GitHub 저장소 에 이슈를 등록하거나 풀 리퀘스트를 제출해 주세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

작가

• 라팔 야니츠키 - rafal@kult.io