에이전트-트위터-클라이언트-MCP

agent-twitter-client 패키지를 사용하여 Twitter와 통합되는 MCP(Model Context Protocol) 서버를 통해 AI 모델이 API에 직접 액세스하지 않고도 Twitter와 상호 작용할 수 있습니다.

특징

인증 옵션 :
- 쿠키 기반 인증(권장)
- 사용자 이름/비밀번호 인증
- Twitter API v2 자격 증명
트윗 작업 :
- 사용자의 트윗 가져오기
- ID로 특정 트윗 가져오기
- 트윗 검색
- 텍스트와 미디어를 포함한 트윗 보내기
- 여론조사 만들기
- 트윗을 좋아요, 리트윗, 인용하세요
사용자 작업 :
- 사용자 프로필 가져오기
- 사용자를 팔로우하세요
- 팔로워와 팔로잉 목록을 얻으세요
Grok 통합 :
- Twitter 인터페이스를 통해 Grok과 채팅하세요
- 대화 ID로 대화 계속하기
- 웹 검색 결과 및 인용문 가져오기
- Grok을 통해 Twitter의 실시간 데이터에 액세스하세요
- 참고 : Grok 기능을 사용하려면 agent-twitter-client v0.0.19 이상이 필요합니다.

선적 서류 비치

개발자 가이드 - 개발자를 위한 포괄적인 가이드
테스트 가이드 - MCP 테스트 지침
에이전트 가이드 - Twitter MCP 사용 방법에 대한 AI 에이전트 가이드
기여 가이드 - 이 프로젝트에 기여하기 위한 지침
변경 내역 - 이 프로젝트의 변경 내역
데모 README - 데모 스크립트 실행 가이드
Grok 예제 - Grok AI 통합 예제에 대한 문서

빠른 시작

설치

지엑스피1

기본 사용법

Twitter 자격 증명으로 .env 파일을 만듭니다( 인증 방법 참조)
MCP 서버를 실행합니다.

# If installed globally
agent-twitter-client-mcp

# If installed locally
npx agent-twitter-client-mcp

데모 스크립트

패키지에는 다양한 기능을 보여주는 예제 스크립트가 포함된 demo 디렉토리가 포함되어 있습니다.

# Clone the repository to access the demo scripts
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp/demo

# Run the interactive demo menu
./run-demo.sh

# Run a specific demo script
./run-demo.sh --script tweet-search.js

# Run Grok AI examples (requires agent-twitter-client v0.0.19)
./run-demo.sh --script simple-grok.js --use-local-agent-twitter-client
./run-demo.sh --script grok-chat.js --use-local-agent-twitter-client

자세한 내용은 데모 README를 참조하세요.

포트 구성

기본적으로 MCP 서버는 포트 3000에서 실행됩니다. 이를 변경해야 하는 경우(예: 이미 포트 3000에서 실행 중인 애플리케이션이 있는 경우) 다음과 같은 몇 가지 옵션이 있습니다.

옵션 1: 환경 변수 사용

PORT 환경 변수를 설정합니다.

PORT=3001 npx agent-twitter-client-mcp

옵션 2: Docker Compose 사용

Docker Compose를 사용하는 경우 .env 파일에서 호스트와 컨테이너 포트를 모두 구성할 수 있습니다.

# .env file
MCP_HOST_PORT=3001    # The port on your host machine
MCP_CONTAINER_PORT=3000  # The port inside the container

그런 다음 실행하세요.

docker-compose up -d

이렇게 하면 호스트의 포트 3001이 컨테이너의 포트 3000에 매핑되어 다른 애플리케이션이 포트 3000을 계속 사용하는 동안 http://localhost:3001 에서 MCP에 액세스할 수 있습니다.

Claude Desktop으로 설정

다음을 구성 파일에 추가하여 Claude Desktop이 이 MCP를 사용하도록 구성하세요.

Windows : %APPDATA%\Claude\claude_desktop_config.json macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "agent-twitter-client-mcp": {
      "command": "npx",
      "args": ["-y", "agent-twitter-client-mcp"],
      "env": {
        "AUTH_METHOD": "cookies",
        "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
      }
    }
  }
}

Claude Desktop을 다시 시작하세요

인증 방법

쿠키 인증(권장)

{
  "AUTH_METHOD": "cookies",
  "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
}

쿠키를 얻으려면:

브라우저에서 Twitter에 로그인하세요
개발자 도구 열기(F12)
애플리케이션 탭 > 쿠키로 이동하세요
auth_token , ct0 , twid 쿠키 값을 복사합니다.
각 쿠키에 Domain=.twitter.com 부분을 포함해야 합니다.

사용자 이름/비밀번호 인증

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "your_email@example.com", // Optional
  "TWITTER_2FA_SECRET": "your_2fa_secret" // Optional, required if 2FA is enabled
}

트위터 API 인증

{
  "AUTH_METHOD": "api",
  "TWITTER_API_KEY": "your_api_key",
  "TWITTER_API_SECRET_KEY": "your_api_secret_key",
  "TWITTER_ACCESS_TOKEN": "your_access_token",
  "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}

사용 가능한 도구

get_user_tweets : 특정 사용자의 트윗을 가져옵니다.
get_tweet_by_id : ID로 특정 트윗을 가져옵니다.
search_tweets : 트윗 검색
send_tweet : 새로운 트윗을 게시합니다
send_tweet_with_poll : 투표와 함께 트윗을 게시합니다.
like_tweet : 트윗 좋아요
retweet : 트윗을 리트윗하다
quote_tweet : 트윗을 인용합니다
get_user_profile : 사용자 프로필 가져오기
follow_user : 사용자를 팔로우합니다
get_followers : 사용자의 팔로워를 가져옵니다
get_following : 사용자가 팔로우하는 사용자를 가져옵니다.
grok_chat : Twitter를 통해 Grok과 채팅
health_check : Twitter MCP 서버의 상태를 확인합니다.

테스트 인터페이스

MCP에는 테스트를 위한 대화형 명령줄 인터페이스가 포함되어 있습니다.

npx agent-twitter-client-mcp-test
# or if installed locally
npm run test:interface

이렇게 하면 다양한 MCP 기능을 테스트할 수 있는 REPL이 시작됩니다.

agent-twitter-client-mcp> help

Available commands:
  health                     Run a health check
  profile <username>         Get a user profile
  tweets <username> [count]  Get tweets from a user
  tweet <id>                 Get a specific tweet by ID
  search <query> [count]     Search for tweets
  post <text>                Post a new tweet
  like <id>                  Like a tweet
  retweet <id>               Retweet a tweet
  quote <id> <text>          Quote a tweet
  follow <username>          Follow a user
  followers <userId> [count] Get a user's followers
  following <userId> [count] Get users a user is following
  grok <message>             Chat with Grok
  help                       Show available commands
  exit                       Exit the test interface

테스트 명령 예

# Run a health check
agent-twitter-client-mcp> health

# Search for tweets
agent-twitter-client-mcp> search mcp 2

# Get a user's profile
agent-twitter-client-mcp> profile elonmusk

# Get tweets from a user
agent-twitter-client-mcp> tweets openai 5

# Chat with Grok
agent-twitter-client-mcp> grok Explain quantum computing in simple terms

사용 예

클로드에게 다음을 요청하세요.

"AI에 대한 트윗을 Twitter에서 검색하세요"
"클로드가 전하는 안녕하세요!"라는 트윗을 게시하세요.
"@OpenAI의 최신 트윗을 받아보세요"
"Grok과 양자 컴퓨팅에 대해 대화하세요"

고급 사용법

미디어 작업

이미지가 포함된 트윗을 게시하려면:

I want to post a tweet with an image. The tweet should say "Beautiful sunset today!" and include this image.

비디오가 포함된 트윗을 게시하려면:

I want to post a tweet with a video. The tweet should say "Check out this amazing video!" and include the video file.

여론조사 만들기

여론조사를 만들려면:

Create a Twitter poll asking "What's your favorite programming language?" with options: Python, JavaScript, Rust, and Go. The poll should run for 24 hours.

Grok과 상호 작용

Grok과 대화하려면:

Use Grok to explain quantum computing to me. Ask it to include some real-world applications.

Grok과 대화를 계속하려면:

Continue the Grok conversation and ask it to elaborate on quantum entanglement.

Grok의 독특한 역량

트위터의 Grok은 단독 Grok API조차 제공하지 않는 실시간 트위터 데이터에 접근할 수 있습니다. 즉, Grok에 다음과 같은 정보를 요청할 수 있습니다.

트위터의 현재 트렌드 주제
특정 주제에 대한 최근 트윗 분석
트위터 사용자와 콘텐츠에 대한 정보
플랫폼에서 논의되는 실시간 이벤트

예시 쿼리:

"지금 트위터에서 가장 인기 있는 주제는 무엇인가요?"
"트위터에서 AI에 대한 감정을 분석하세요"
"사람들은 최근 Apple 이벤트에 대해 어떻게 말하고 있나요?"
"오늘 논의되고 있는 인기 있는 밈코인에 대한 정보를 보여주세요"

Grok 인증 요구 사항

Grok 기능을 사용하려면 적절한 인증이 필요합니다. MCP는 두 가지 방법을 지원합니다.

쿠키 인증 (권장):
- 쿠키는 JSON 배열 형식이어야 합니다.
- 예: TWITTER_COOKIES=["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com", "twid=u=YOUR_USER_ID; Domain=.twitter.com"]
- 필수 쿠키는 auth_token , ct0 , twid 입니다.
사용자 이름/비밀번호 인증 :
- 환경에서 TWITTER_USERNAME 및 TWITTER_PASSWORD 설정하세요.
- 어떤 경우에는 Cloudflare 보호가 발생할 수 있습니다.

Grok 요금 제한

Grok에는 사용에 영향을 줄 수 있는 요금 제한이 있습니다.

프리미엄이 아닌 계정: 2시간당 25개의 메시지
프리미엄 계정: 더 높은 한도

MCP는 제한에 도달하면 응답으로 속도 제한 정보를 반환합니다.

Grok 사용에 대한 자세한 내용은 Grok 예제 문서를 참조하세요.

문제 해결

인증 문제

쿠키 인증 문제

쿠키 인증에 문제가 있는 경우:

쿠키 만료 : Twitter 쿠키는 일반적으로 일정 기간 후에 만료됩니다. Twitter에서 로그아웃했다가 다시 로그인하여 쿠키를 새로 고침해 보세요.
쿠키 형식 : 쿠키가 올바른 도메인을 가진 문자열의 JSON 배열로 올바르게 형식화되었는지 확인하세요.
필수 쿠키 : 필수 쿠키인 auth_token , ct0 , twid 포함했는지 확인하세요.

올바르게 포맷된 쿠키의 예:

"TWITTER_COOKIES": "[\"auth_token=1234567890abcdef; Domain=.twitter.com\", \"ct0=abcdef1234567890; Domain=.twitter.com\", \"twid=u%3D1234567890; Domain=.twitter.com\"]"

자격 증명 인증 문제

사용자 이름/비밀번호 인증에 문제가 있는 경우:

2단계 인증 : 계정에 2FA가 활성화된 경우 TWITTER_2FA_SECRET 을 제공해야 합니다.
계정 잠금 : 로그인 시도 실패 횟수가 너무 많으면 계정이 잠길 수 있습니다. 계정 확인 요청 이메일을 확인하세요.
캡차 챌린지 : Twitter는 클라이언트가 자동으로 처리할 수 없는 캡차 챌린지를 제시할 수 있습니다.

API 인증 문제

API 인증 문제의 경우:

API 키 권한 : 수행하려는 작업에 필요한 권한이 API 키에 있는지 확인하세요.
속도 제한 : Twitter API에는 속도 제한이 있어 이를 초과하면 오류가 발생할 수 있습니다.
API 변경 : Twitter는 가끔 API를 변경하는데, 이로 인해 호환성 문제가 발생할 수 있습니다.

작업 오류

트윗 게시 실패

트윗을 게시할 수 없는 경우:

콘텐츠 제한 : Twitter는 콘텐츠 정책을 위반하는 트윗을 차단할 수 있습니다.
미디어 형식 문제 : 미디어가 올바르게 포맷되고 인코딩되었는지 확인하세요.
속도 제한 : Twitter는 게시 빈도를 제한합니다.

검색 문제

검색이 작동하지 않는 경우:

쿼리 구문 : 검색어가 Twitter의 검색 구문을 따르는지 확인하세요.
검색 제한 : 일부 검색 모드에는 제한이 있거나 특정 권한이 필요할 수 있습니다.

그록 이슈

Grok 기능이 작동하지 않는 경우:

버전 요구 사항 :
- Grok에는 agent-twitter-client v0.0.19 이상이 필요합니다.
- 현재 패키지는 기본 기능을 위해 v0.0.18을 사용합니다.
- 데모 스크립트의 경우 --use-local-agent-twitter-client 플래그를 사용하여 v0.0.19를 임시로 설치합니다.
인증 문제 :
- 쿠키 형식: 쿠키가 올바른 JSON 배열 형식인지 확인하세요.
- 쿠키 유효 기간: Twitter 쿠키는 특정 기간 후에 만료됩니다.
- Cloudflare Protection: 사용자 이름/비밀번호 인증이 Cloudflare에 의해 차단될 수 있습니다.
- 프리미엄 요구 사항: Grok에 액세스하려면 Twitter 프리미엄 구독이 필요합니다.
요금 제한 :
- 프리미엄이 아닌 계정: 2시간당 25개의 메시지
- 오류 메시지: "요금 제한: 한도에 도달했습니다..."
- 해결 방법: 요금 제한이 재설정될 때까지 기다리거나 프리미엄 계정으로 업그레이드하세요.
환경 파일 위치 :
- 데모 스크립트의 경우 자격 증명이 루트 .env 파일이 아닌 demo/.env 에 있는지 확인하세요.
- --debug-env 플래그를 사용하여 어떤 환경 변수가 로드되는지 확인하세요.

Grok 문제에 대한 자세한 문제 해결 방법은 Grok 예제 문서를 참조하세요.

서버 문제

건강 검진

health_check 도구를 사용하여 서버 문제를 진단합니다.

Run a health check on the agent-twitter-client-mcp server to diagnose any issues.

건강 검진에서는 다음 사항을 보고합니다.

인증 상태
API 연결
메모리 사용량

벌채 반출

서버는 콘솔과 파일에 모두 기록합니다.

error.log : 오류 수준 메시지를 포함합니다.
combined.log : 모든 로그 메시지를 포함합니다.

자세한 오류 정보는 이 로그에서 확인하세요.

개발

필수 조건

노드.js 18+
엔피엠

설정

저장소를 복제합니다

git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp

종속성 설치

npm install

구성을 사용하여 .env 파일을 만듭니다.

AUTH_METHOD=cookies
TWITTER_COOKIES=["cookie1=value1", "cookie2=value2"]

프로젝트를 빌드하세요

npm run build

서버를 시작합니다

npm start

환경 변수

인증 변수 외에도 다음을 설정할 수 있습니다.

LOG_LEVEL : 로깅 수준 설정(오류, 경고, 정보, 디버그)
NODE_ENV : 환경 설정(개발, 프로덕션)

도커

Docker를 사용하여 서버를 실행할 수도 있습니다.

Docker 직접 사용하기

# Build the Docker image
docker build -t agent-twitter-client-mcp .

# Run the container with environment variables
docker run -p 3000:3000 \
  -e AUTH_METHOD=cookies \
  -e TWITTER_COOKIES='["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com"]' \
  agent-twitter-client-mcp

Docker Compose 사용

Twitter 자격 증명으로 .env 파일을 만듭니다.
docker-compose로 실행:

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Docker의 환경 변수

Docker 컨테이너에 환경 변수를 전달하는 방법은 여러 가지가 있습니다.

docker-compose.yml 파일에서 (이미 구성됨)
.env 파일을 통해 (docker-compose에 권장됨)
docker run 명령에서 직접 (위에 표시된 대로)

지속 로그

docker-compose 구성에는 로그에 대한 볼륨 마운트가 포함되어 있습니다.

volumes:
  - ./logs:/app/logs

이렇게 하면 프로젝트 폴더의 logs 디렉토리에 로그가 저장됩니다.

보안 고려 사항

자격 증명 저장소 : 환경 변수나 보안 볼트를 사용하여 자격 증명을 안전하게 저장합니다.
속도 제한 : Twitter API 남용을 방지하기 위해 속도 제한을 구현합니다.
콘텐츠 검증 : 악의적인 사용을 방지하기 위해 게시하기 전에 모든 콘텐츠를 검증합니다.

특허

MIT

Integrations