Twitter/X MCP

Twitter/X MCP를 사용하면 MCP 클라이언트가 공개 X 게시물, 답글, 프로필을 읽거나 X를 검색할 수 있습니다. 기본적으로 Rettiwt를 사용하므로 X 개발자 플랜이 필요 없습니다. 액세스 권한이 있다면 공식 X API로 전환할 수 있습니다.

요구 사항

• Node.js 22 릴리스 계열의 22.21.0 이상. 현재 Rettiwt 릴리스는 Node 23 이상을 지원하지 않습니다.

• RETTIWT_API_KEY가 필요합니다. API 모드를 선택하면 공식 X API 자격 증명도 사용할 수 있습니다.

Related MCP server: X MCP Server

빠른 시작

패키지가 게시되면 MCP 클라이언트가 클론 없이 실행할 수 있습니다:

npx -y @granitebps/twitter-mcp

TWITTER_MODE를 생략하면 서버는 Rettiwt를 선택합니다. 클라이언트 구성에 RETTIWT_API_KEY를 전달하세요.

서버는 stdio를 사용합니다. stdout은 MCP 트래픽 전용으로 남겨 두세요.

클론 저장소에서 실행

서버를 개발하거나 클론을 직접 사용하려면:

git clone https://github.com/granitebps/twitter-mcp.git
cd twitter-mcp
npm ci
npm run build

컴파일된 진입점을 MCP 클라이언트에 지정하세요:

node /absolute/path/to/twitter-mcp/dist/cli.js

소스 변경 후 npm run build를 실행하세요. 클라이언트의 stdio 명령으로 src나 npm run dev를 사용하지 마세요. stdout의 빌드 로그는 MCP 메시지를 손상시킬 수 있습니다.

클라이언트 구성

각 예시는 npm 패키지로 시작한 뒤 로컬에 해당하는 방식이 이어집니다. /absolute/path/to/twitter-mcp를 클론 경로로, your_key_here를 Rettiwt 키로 바꾸세요. 키가 포함된 구성 파일은 커밋하지 마세요.

Claude

npm 패키지를 Claude Code에 추가하세요:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp

로컬 빌드의 경우:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js

Claude Code는 기본적으로 로컬 범위를 사용합니다. twitter 앞에 --scope user를 추가하면 서버가 여러 프로젝트에서 사용 가능합니다.

Claude Desktop은 claude_desktop_config.json에서 동일한 서버를 읽습니다. 파일을 편집한 후 앱을 다시 시작하세요.

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

로컬 빌드의 경우 command와 args를 다음으로 바꾸세요:

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Codex

npm 패키지를 신뢰할 수 있는 프로젝트의 ~/.codex/config.toml 또는 .codex/config.toml에 추가하세요:

[mcp_servers.twitter]
command = "npx"
args = ["-y", "@granitebps/twitter-mcp"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

로컬 빌드의 경우:

[mcp_servers.twitter]
command = "node"
args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

파일을 편집한 후 Codex를 다시 시작하세요. CLI, IDE 확장, 데스크톱 앱은 같은 컴퓨터에서 이 구성을 공유합니다.

OpenCode

npm 패키지를 opencode.json 또는 opencode.jsonc에 추가하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twitter": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/twitter-mcp"],
      "enabled": true,
      "environment": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

로컬 빌드의 경우 command 배열을 다음으로 바꾸세요:

{
  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Cursor

프로젝트의 .cursor/mcp.json에 npm 패키지를 추가하거나, 전역으로 사용하려면 ~/.cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

로컬 빌드의 경우 command와 args를 다음으로 바꾸세요:

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

제공자

Rettiwt 설정

이 서버에서는 Rettiwt가 인증된 사용자 모드를 요구합니다. 게스트 모드는 지원되지 않습니다.

1. Rettiwt 인증 절차에 따라 API 키를 생성합니다.

2. 이 키를 MCP 클라이언트 환경의 RETTIWT_API_KEY로 저장합니다.

3. TWITTER_MODE를 설정하지 않거나 TWITTER_MODE=rettiwt라고 명시적으로 설정하여 서버를 시작합니다.

Rettiwt 키에는 X 세션 쿠키가 포함되어 있으며 계정과 동일한 액세스 권한을 가집니다. 키는 비밀번호처럼 다뤄야 합니다. 커밋하거나 이슈에 붙여넣거나 로그로 남기거나 명령줄 인수로 전달하지 마세요. 본인이 소유하거나 액세스 권한을 부여받은 계정의 키만 사용하세요.

Rettiwt는 비공식 도구입니다. X의 자동화 규칙은 API 외 웹사이트 자동화를 금지하고, 위반 시 계정이 정지될 수 있다고 경고합니다. 이 모드를 사용하기 전에 X 규칙을 읽어보세요. 이 모드를 사용할 때의 규정 준수 및 계정 위험은 사용자가 감수해야 합니다.

공식 X API 설정

Bearer 토큰을 사용하려면:

TWITTER_MODE=api
TWITTER_BEARER_TOKEN=your_bearer_token

또는 전체 OAuth 자격 증명을 제공하세요:

TWITTER_MODE=api
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_SECRET=your_access_secret

X Developer Portal에서 자격 증명을 생성하세요. X가 API 액세스와 가격을 제어하므로 이 모드를 선택하기 전에 최신 약관을 확인하세요.

구성

서버는 시작 시 OAuth 구성이 불완전하면 거부합니다. 자격 증명은 OS 환경 변수에 저장되며 get_server_info을 통해 절대 반환하지 않습니다.

도구

max_results는 기본 10이며 1부터 100까지 허용됩니다. 성공적인 호출은 구 클라이언트에 대한 JSON 텍스트와 함께 구조화된 MCP 콘텐츠를 반환합니다. 컬렉션 도구는 항목을 JSON 텍스트로 반환하고 커서와 경고를 구조화된 콘텐츠에 담습니다.

오류

도구 실패 시 다음의 안정적인 코드를 사용합니다:

• INVALID_INPUT

• AUTH_REQUIRED

• AUTH_FAILED

• NOT_FOUND

• RATE_LIMITED

• UPSTREAM_UNAVAILABLE

• TIMEOUT

• UNSUPPORTED_OPERATION

• INTERNAL_ERROR

오류 응답은 제공자와 재시도 가능 여부를 명시합니다. 자격 증명이나 원본 업스트림 응답 본문은 포함하지 않습니다.

아키텍처

stdio CLI
  -> validated environment configuration
  -> MCP server and tool handlers
  -> TwitterProvider contract
       -> Rettiwt adapter
       -> official X API adapter

도메인 스키마는 특정 제공자에 의존하지 않습니다. 각 제공자 어댑터는 업스트림 데이터를 매핑하고, 한도와 시간 초과를 부과하며, 오류를 변환합니다. src/index.ts를 import 해도 서버는 시작되지 않습니다.

개발

npm ci
npm run check

npm run check는 포맷, 린트, 타입, 커버리지, 프로덕션 빌드, npm 패키지 콘텐츠, 암호화 재현 설치까지 검사합니다. 기본 테스트 스위트는 가짜 객체를 사용하며 X 자격 증명이 필요하지 않습니다.

유용한 포커스 명령:

npm test
npm run typecheck
npm run lint
npm run build
npm run check:package
npm run check:install
npx @modelcontextprotocol/inspector node dist/cli.js

실시간 Rettiwt 스모크 테스트

실시간 스모크 테스트는 컴파일된 stdio 서버를 시작하고 get_tweet, get_tweet_users, get_user_profile, search_tweets를 호출합니다. 사용자 이름과 검색어는 선택된 게시물에서 파생합니다.

RETTIWT_API_KEY=your_key_here \
TWITTER_LIVE_TWEET_ID=1234567890123456789 \
npm run test:live

작성자 프로필이 아직 공개된 공개 게시물을 선택하세요. 변수 중 하나라도 누락되면 실시간 서버를 시작하거나 네트워크 요청을 만들지 않고 명령이 중지됩니다. npm run check 또는 일반 CI의 일부로 실행되지 않습니다.

릴리스 검증

테스트 자동화는 구성, 제공자 어댑터, MCP 호출, 컴파일된 stdio 진입점, npm 패키지 설치를 다룹니다. Rettiwt 실시간 스모크 테스트는 선택 사항이며 일반 CI에서 실행하지 않습니다. 1.0.0 버전은 실시간 업스트림 검증 없이 준비되었습니다.

관리자는 릴리스 가이드에 따라 npm, MCP Registry, GitHub 릴리스 수동 프로세스를 진행할 수 있습니다. 실시간 테스트는 리포지토리 시크릿에서 자격 증명을 읽어야 하며, 신뢰할 수 없는 pull request에서는 실행하지 마세요.

문제 해결

Rettiwt 키 누락

시작 시 RETTIWT_API_KEY is required in rettiwt mode와 같은 메시지가 반환되면 MCP 클라이언트 설정에서 키를 설정하세요. 데스크톱 클라이언트는 셸의 .env 파일을 자동으로 소개받지 않습니다.

Rettiwt 인증 실패

Invalid authentication data 또는 AUTH_FAILED가 표시되면 새 Rettiwt 키를 생성하고 X 세션이 여전히 유지되는지 확인하세요. 실패한 키를 이슈에 올리지 마세요.

속도 제한

RATE_LIMITED가 발생하면 재시도 전에 대기하고 요청 빈도를 줄이세요. 제공자가 반환하는 경우 retryAfterSeconds를 확인하세요.

공식 API 401 또는 403

자격 증명 세트, 앱 권한, 엔드포인트 액세스, 현재 X API 플랜을 확인하세요.

Node 엔진 경고

Node.js 22.21.0 또는 최신 Node 22 릴리스로 실행하세요. 최신 Rettiwt 의존성에서는 Node 23 이상을 사용하지 마세요.

라이선스

ISC