x-mcp

에이전트와 함께 X 계정을 운영하기 위한 의견이 반영된 MCP 서버입니다.

X API의 래퍼가 아닙니다. API가 알려주지 않는 네 가지를 아는 작은 운영자입니다:

1. For You가 어떻게 순위를 매기는지 — X가 오픈소스로 공개한 알고리즘(xai-org/x-algorithm)의 가중치, 게이트, 필터가 모든 도구에 가드레일과 조언으로 내장되어 있습니다: 상호 팔로우 시 답글 가중치 5→20, 링크 공유 20, 좋아요 0.5; 10초 초과 동영상 엄격 적용; @멘션 1개 이하; 참여 유도 금지; 오리지널 포스트 간 4시간 이상 간격; 첫 번째 좋아요가 아웃오브네트워크 코퍼스를 여는 조건; 팔로워 1천 미만 콜드스타트 상승 효과; 24시간/48시간 윈도우.

2. 종량제 API가 실제로 허용하는 것 — 2026년부터 X는 요청받지 않은 답글을 거부하고 셀프서브에서 팔로우, 좋아요, 인용 포스트를 제거했습니다. 도구는 허용되는 모든 것을 수행하고 나머지는 인간에게 원탭 의도 링크를 넘긴 뒤, $0.001 소유 읽기를 통해 인간이 한 일을 자동 조정합니다.

3. 각 호출의 비용 — 로컬 원장이 X의 리소스별 가격(24시간 중복 제거 포함)을 반영하고, 월간 예산을 강제하며, $0.20 "URL 포함 포스트" 전에 경고합니다.

4. 비즈니스가 유지하는 것 — 참여한 모든 사람의 관계 원장(팔로우할 사람 포함), 최적 시간을 학습하는 캘린더, 모든 세션이 공유하는 브랜드 북, 아이디어 파이프라인, 인사이트/리포트 루프를 통해 에이전트가 감이 아닌 자체 수치로 방향을 잡습니다.

MCP TypeScript SDK v2 기반으로 구축되었습니다. 기본은 stdio, Streamable HTTP는 선택 사항입니다. SDK와 zod 외 런타임 의존성은 없습니다.

도구

리소스: x://playbook (규칙), x://boundary (API가 허용하는 것), x://handoff (실시간 인간 대기열). 프롬프트: operate (작동 루프).

Related MCP server: X(Twitter) V2 MCP Server

설정

1. 앱 만들기 https://console.x.com → OAuth 2.0 활성화 → 앱 유형 네이티브 앱 (공개, PKCE) 또는 자동화 앱/봇 (비공개, 클라이언트 시크릿 제공) → 리다이렉트 URI http://127.0.0.1:8477/callback 추가 → 클라이언트 ID(비공개인 경우 시크릿) 복사. 크레딧을 충전하세요(종량제).

2. 구성 — 환경 변수는 환경 또는 ~/.x-mcp/.env에서 읽습니다(현재 디렉토리에서 읽지 않으므로 악성 저장소의 .env가 토큰을 리다이렉트할 수 없습니다):

   cd x-mcp && npm install && npm run build
   mkdir -p ~/.x-mcp/media && cp .env.example ~/.x-mcp/.env   # set X_CLIENT_ID (+ X_CLIENT_SECRET if confidential)

   에이전트가 업로드할 수 있는 미디어는 ~/.x-mcp/media(또는 X_MCP_MEDIA_ROOT의 디렉토리)에 있어야 합니다 — 데모 동영상을 거기에 넣으세요.

3. 한 번 로그인 (브라우저가 열리고 토큰이 ~/.x-mcp/tokens.json에 저장, 모드 0600):

   node dist/bin.js login

4. 에이전트에 연결.

   Hermes (~/.hermes/config.yaml):

   mcp_servers:
     x:
       command: node
       args: ["/absolute/path/to/x-mcp/dist/bin.js"]
       env:
         X_CLIENT_ID: "…"
         X_CLIENT_SECRET: "…"          # confidential apps only
         X_MCP_MONTHLY_BUDGET_USD: "25"
         X_MCP_REQUIRE_APPROVAL: "true" # default; keep until you have X's AI-reply approval
       timeout: 180

   Claude Code:

   claude mcp add x -e X_CLIENT_ID=… -e X_MCP_REQUIRE_APPROVAL=true -- node /absolute/path/to/x-mcp/dist/bin.js

   stdio 대신 HTTP: X_MCP_HTTP_TOKEN=SECRET node dist/bin.js --http --port 8478 → url: http://127.0.0.1:8478/mcp, 헤더 Authorization: Bearer SECRET. 토큰은 항상 필요합니다(설정하지 않으면 생성되어 출력됩니다); Host/Origin은 localhost에 대해 확인됩니다.

5. 루프 실행. 에이전트에게 operate 프롬프트를 사용하도록 요청하세요(또는 붙여넣기). node dist/bin.js queue로 대기 중인 항목을 확인하세요; node dist/bin.js approve --all은 대기 중인 API 작업을 실행합니다; 인간 전용 작업은 의도 링크를 탭하고 handoff(reconcile)를 실행(또는 에이전트가 하도록)하여 대기열이 스스로 비워지게 하세요.

6. tick을 타이머에 설정 (15분마다면 충분) 예약된 포스트가 나가고, 핸드오프가 조정되고, 메트릭이 insights용으로 스냅샷됩니다:

   */15 * * * * cd /absolute/path/to/x-mcp && node dist/bin.js tick >> ~/.x-mcp/tick.log 2>&1

   (Hermes 사용자: schedule(run_due) + handoff(reconcile) + post_performance를 호출하는 cron 작업도 동일합니다.)

구성 (환경)

무엇을 거부하고 그 이유

• 게시물에 @멘션이 두 개 이상인 경우 → X의 실시간 LLM 스팸 점수로 라우팅됩니다. 크레딧은 답글로 달아 주세요.

• "좋아요 / RT / 태그" → SpamHighRecall, 누구도 예외 없음.

• 10.0초 이하 동영상 → 비디오 헤드가 0이고 모든 비디오 코퍼스에서 제외됩니다.

• 게시물 하나에 동영상+이미지 → 비디오 코퍼스에서 제외.

• 4시간 이내의 두 번째 오리지널 → 공유 슬레이트에서 ×0.625, 콜드 스타트 리프트가 요청당 게시물 하나를 선택.

• 동일한 답글 텍스트 두 번 → 복붙 클러스터링.

• 나를 @멘션하지 않은 게시물에 답글 → X가 거부, 대신 의도 링크를 받음.

• 월 예산을 초과하는 모든 지출.

소프트한 모든 것은 force: true로 재정의할 수 있지만, 이 경우 항상 사람의 승인 대기열로 라우팅됩니다. 미디어 루트, 예산, X 자체 제한은 재정의할 수 없습니다.

보안 모델(요약)

• 토큰/상태는 ~/.x-mcp(0700 디렉터리, 0600 파일)에 저장됩니다. 서버와 x-mcp approve CLI는 이를 안전하게 공유합니다(쓰기 전 다시 로드, 최신 토큰 세트를 덮어쓰지 않음).

• 에이전트는 임의의 파일을 읽을 수 없습니다. media_paths는 미디어 루트 아래에서 확인되어야 하며, ID는 숫자 스노우플레이크로 검증됩니다(다른 엔드포인트로의 ../ 경로 밀반입 불가).

• 되돌릴 수 없거나 정책에 민감한 작업(delete_post, 모든 force, DM, 승인 모드)은 CLI에서 사람의 탭이 필요합니다. delete_post는 이 서버가 사용자 소유로 인식하는 게시물만 허용합니다.

• 도구 출력의 타사 텍스트는 지침이 아닌 데이터로 표시됩니다. HTTP 모드에는 베어러 토큰이 필요하며 Host/Origin을 검증합니다.

읽어야 할 정책 참고 사항

• X의 자동화 규칙(2026년 4월)은 AI 답글 봇에 대한 사전 서면 승인, 사용자 상호작용당 자동 답글 1회, 중복 게시물 금지, 대량 팔로우/좋아요/DM 금지, 자동화 계정 라벨(설정 → 내 계정 → 계정 정보 → 자동화)을 요구합니다. 이 서버는 기계적인 부분을 강제하며, 승인과 라벨은 직접 받아 설정해야 합니다.

• 제출한 개발자 계약 사용 사례에는 에이전트가 수행하는 작업(게시, 자체 지표 읽기, 틈새 리서치)을 설명해야 합니다.

개발

npm test          # rules engine + full server through an in-memory MCP client against a mock X API
npm run typecheck
npm run build

출처: X API 문서(docs.x.com, 2026-08-19 읽음: 가격, 게시물 관리 제한, 변경 로그, 미디어 v2, OAuth 2.0) 및 xai-org/x-algorithm@11a71f8(home-mixer/params/param.rs, scorers/, filters/, visibility-filtering/, phoenix/, grox/). 전체 연구는 x-algorithm 클론의 docs/FOR_YOU_PLAYBOOK.md에서 파일:줄 인용과 함께 확인하세요.

MIT.