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를 사용하는 것입니다.

pip install x-twitter-mcp

옵션 3: 소스에서 설치

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

저장소 복제 :
git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git cd x-twitter-mcp-server
가상 환경 설정 (선택 사항이지만 권장):
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
종속성 설치 : uv 사용(프로젝트에서 uv.lock 사용하므로 권장):
uv sync
또는 pip 사용하면:
pip install .
환경 변수 구성 :
- 프로젝트 루트에 .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에서 설치한 경우:

x-twitter-mcp-server

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

uv run x-twitter-mcp-server

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

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

fastmcp dev src/x_twitter_mcp/server.py

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

Starting TwitterMCPServer...

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에서 설치한 경우:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "x-twitter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "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"
      }
    }
  }
}

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

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-twitter-mcp-server",
        "run",
        "x-twitter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

"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