x-use: X (Twitter)용 브라우저 네이티브 AI 에이전트

Browser-native AI agents for X (Twitter). Multi-account, MCP-ready, no X API key required.

x-use는 사용자의 X 세션으로 인증된 비동기(async) Patchright Chromium 브라우저를 사용합니다. 이의 MCP 도구들은 게시물 작성, 답글 달기, 검색, 받은 편지함 읽기, 검토된 메시지, 팔로우, 로컬 리드 및 캠페인 초안 작성을 포함합니다. 격리된 계정 컨텍스트(Isolated account contexts), 브라우저 소유권 잠금(browser ownership locks), 내구성 있는 로컬 액션 예산(durable local action budgets), 그리고 불확실한 결과 추적(uncertain-outcome tracking) 기능이 공유 세션을 보호합니다.

공식 X API는 사용되지 않습니다. 도구들은 기본적으로 초안 작성을 통해 작업하며, 메시지 및 팔로우는 항상 개별적인 초안 승인을 필요로 합니다. 브라우저의 도전 과제(Browser challenges)와 속도 제한(rate limits)은 운영자가 복구할 수 있도록 작업을 일시 중단합니다. 브라우저 런타임 및 아웃리치 가이드(Browser runtime and outreach guide)는 설정, 제한 사항, 복구 방법, 그리고 현재의 한계점을 설명합니다.

상세한 런타임 감사 기록(detailed runtime audit)은 제어 장치, 테스트 증거, 남아 있는 호환성 격차를 기록합니다. 도구 검증 매트릭스(tool validation matrix)는 등록된 모든 도구에 대해 라이브 계정 결과와 격리된 테스트 결과를 구분합니다.

x-use 3.0.0 버전에서는 검토된 아웃리치, 구조화된 메시지 및 알림 기능, 그리고 일곱 가지 에이전트 스킬을 제공합니다. 2.x에서 업그레이드할 때는 마이그레이션 노트(migration notes)를 확인하십시오. 사용자가 소유했거나 관리 권한을 부여받은 계정을 사용해야 합니다.

PyPI (CLI 및 MCP 서버)에서 설치하는 방법:

python -m pip install --upgrade x-use-mcp
python -m patchright install chromium

기존 체크아웃(existing checkout)의 경우, 다음 한 가지 명령어로 필요한 경우 uv를 설치하고, 잠긴 종속성들을 .venv에 동기화하며, 일치하는 Chromium을 설치하고, 누락된 샘플 구성을 생성한 후 x-use doctor를 실행합니다:

py -3 scripts/setup_uv.py

macOS/Linux에서는 python3 scripts/setup_uv.py를 사용하십시오. Python 3.10 이상 버전과 venv/ensurepip, 그리고 다운로드를 위한 네트워크 접속이 필요합니다. 새로운 환경은 호출하는 Python이 Python 3.10~3.14인 경우 해당 버전을 사용하며, 그렇지 않으면 Python 3.12로 폴백(fallback)됩니다. 기존 .venv는 재사용됩니다. 개발 도구를 추가하려면 --dev를 추가하십시오. Linux 호스트의 누락된 브라우저 라이브러리는 OS 관리자 권한이 필요할 수 있는 --with-system-deps를 명시적으로 사용할 수 있습니다. 플랫폼 설치 프로그램은 X_USE_HOME을 설정합니다.

안정적인 사용자별 데이터 디렉터리(또는 기존 값을 유지)로 설정하고, 해당 값을 MCP config 스니펫에 출력합니다. 설정을 완료하면 최소한의 기본 config/settings.json 파일과, 해당 파일이 누락된 경우에만 비활성 샘플 계정이 생성됩니다. 다음 명령어를 실행하여 본인 계정과 쿠키를 추가하세요: x-use init

전체 레포지토리를 하나의 명령어로 복제하고 설정하려면, 플랫폼 설치 프로그램은 동일한 uv 설정을 사용합니다:

Windows (PowerShell):

iex "& { $(irm https://raw.githubusercontent.com/ihuzaifashoukat/x-use/main/install.ps1) }"

macOS / Linux / Git Bash:

curl -fsSL https://raw.githubusercontent.com/ihuzaifashoukat/x-use/main/install.sh | bash

또는 수동 방식:

git clone https://github.com/ihuzaifashoukat/x-use.git
cd x-use
pip install -e .

Python 3.10 이상 및 호환 Chromium 브라우저가 필요합니다. python -m patchright install chromium을 사용하여 기본 드라이버의 Chromium을 설치하거나, mcp.browser_channel를 chrome 또는 msedge로 설정하여 설치된 브라우저를 사용하세요. 선택적인 mcp.browser_backend="playwright"는 playwright 패키지 추가와 이에 맞는 자체 브라우저 설치가 필요합니다. 레거시 CLI 배치 엔진은 Selenium을 통해 계속 사용할 수 있습니다.

어떤 유능한 에이전트라도 이 레포지토리를 가리키면, x-use를 스스로 설치하고 구성할 수 있습니다. 루트에 있는 SKILL.md는 설치 및 구성 스킬입니다. 여기에는 전제 조건, pip install, Claude Desktop, Claude Code, Codex, Cursor, Windsurf용 MCP 클라이언트 등록, 클라이언트 재시작, 쿠키 기반 계정 설정, 키워드, 페르소나가 포함됩니다.

npx skills add ihuzaifashoukat/x-use

또는 docs/SETUP_PROMPT.md에 있는 원샷 프롬프트를 클라이언트에 붙여넣으세요. 직접 구동하는 것을 선호하나요? 계속 읽어보세요.

x-use init # 대화형 마법사: 프리셋, 계정 + 쿠키 가져오기, LLM 키
x-use doctor # 브라우저/드라이버, 쿠키, LLM 키, 프록시 확인

X_USE_HOME을 설정하세요.

설정 후 절대적으로 개인적인 디렉터리로 이동한 다음, 동일한 값을 MCP 클라이언트 환경에서 사용하십시오. PyPI 설치에는 Patchright 시작 구성과 비활성 샘플 계정이 포함되어 있으며, 소스 체크아웃에도 전체 프리셋 라이브러리가 제공됩니다. 명시적으로 교체하도록 선택하지 않는 한 기존 설정은 유지됩니다.

그런 다음 AI 클라이언트를 연결합니다. 이것을 claude_desktop_config.json에 붙여넣으십시오.

(Claude Desktop > 설정 > 개발자 > 구성 편집); 동일한 command/args 쌍이 stdio 서버를 실행하는 모든 MCP 클라이언트에서 작동합니다:

{
"mcpServers": {
"x-use": {
...

X_USE_HOME 플레이스홀더를 설정 중에 사용한 디렉터리로 교체하십시오 (Windows 경로는 C:/Users/you/AppData/Local/x-use와 같이 슬래시를 사용할 수 있습니다).
만약 x-use가 클라이언트의 PATH에 없다면, 설치 프로그램이 출력한 전체 경로를 사용하십시오 (예: .venv/bin/x-use 또는 .venv\Scripts\x-use.exe). 클라이언트를 다시 시작한 다음, list_accounts를 요청하십시오.

초안 모드(Draft mode)는 기본적으로 활성화되어 있습니다. 일반적인 게시 도구는 approve_draft에 대해 검토 가능한 초안을 반환합니다. 운영자는 `

운영자가 자동 배수(auto-drain)를 활성화하지 않은 경우 호출합니다.

인박스(Inbox) 읽기는 현재 보이는 대화 및 메시지로 제한되며 부분적입니다. get_inbox와 search_conversations는 다음 매개변수를 받습니다: folder="inbox"|"requests"|"other" , inbox_filter="all"|"unread"|"read" , 그리고 unread_first. 네이티브 미읽음(Unread) 선택 및 보이는 미읽음 표시기는 결과에 그 증거를 포함합니다. 알 수 없는 미읽음 상태는 그대로 알 수 없는 상태로 유지됩니다. 다른 요청은 스팸이거나 우선순위가 낮은 것일 수 있습니다. 요청 목록화는 이를 받지 않습니다. 대화의 이전 메시지에 대해서는, 결과에서 next_before_message_id를 다음 호출의 before_message_id로 전달합니다. 이 커서는 현재 보이는 대화 창만 페이지 처리합니다. 대화를 열면 읽음으로 표시될 수 있습니다.

get_notifications(account="personal", view="all", limit=20)는 구조화된 알림을 읽습니다. '멘션(Mentions)' 탭의 경우 view="mentions"를 사용하십시오. 결과에는 행위자, 관련 게시물 또는 미리보기, 타임스탬프 및 지원되는 이벤트 유형 증거가 포함됩니다. X가 이를 노출하지 않는 경우 미읽음 상태와 알림 ID는 null로 유지됩니다. 읽기는 경계 지어져 부분적이며, 알림을 방문하는 것은 이를 읽음으로 표시할 수 있습니다.

get_account_analytics는 오직 증거 기반의 로그인한 소유자 분석 가용성만 보고합니다. 관찰된 화면은 X Premium 결제벽(paywall)입니다. 이 경우 메트릭 없이 premium_required를 반환합니다. 지원되지 않는 레이아웃은 unsupported_dom을 반환합니다. 이는 분석 대시보드를 노출하지 않으며, get_metrics에서 로컬 액션 메트릭을 대체하지 않습니다.

대화형 사용에는 LLM 키가 필요하지 않습니다: 귀하의 MCP 클라이언트(Claude, Codex 등)가 사고를 처리하고, get_tweet/prepare_reply를 통해 트윗 이미지를 보고, 쓰기 도구에 명시적인 텍스트를 전달합니다. 선택적 서버 측 LLM(llm)

block)은 컴포지트 툴(composite tools), "auto" 텍스트 및 배경 자동화만 구동합니다.

초안은 data/drafts.jsonl에 저장되며;

; 큐는 data/engagement_queue.jsonl에 저장됩니다.

두 가지 모두 재시작 후에도 유지됩니다.

툴(Tools)은 모델이 호출하는 것입니다. 프롬프트(Prompts)와 리소스(Resources)가 프로토콜의 나머지 두 축을 이루며, x-use는 이 둘 다를 처리합니다.

**프롬프트(Prompts)**는 워크플로우이며, 모든 MCP 클라이언트에서 사용할 수 있습니다. 번들된 SKILL.md 파일은 에이전트 스킬(Agent Skills)을 구현하는 클라이언트에서만 작동하며, 설치가 필요 없고 클라이언트가 프롬프트를 표시하는 곳이라면 어디든 나타납니다.

**리소스(Resources)**는 클라이언트가 턴을 소비하지 않고 첨부할 수 있는 읽기 전용 컨텍스트입니다. 이들 중 어느 것도 브라우저를 시작하지 않으며, 모두 툴과 동일한 마스킹을 실행하므로 쿠키, 비밀번호 또는 프록시 자격 증명이 외부로 유출되지 않습니다.

x-use init

(또는 x-use skills install)

이 명령어는 Claude Code와 Codex를 위한 일곱 가지 에이전트 스킬을 설치합니다: x-use (개요), x-use-setup (온보딩), x-use-engage (리서치 및 답글 작성), x-use-inbox (메시지, 읽지 않은/요청 폴더, 알림), x-use-content (콘텐츠 생성), x-use-review (일일 요약), 그리고 x-use-threads (스레드 읽기, 검토 및 이어가기). Claude Code의 경우, 플러그인 설정 가이드는 마켓플레이스 설치와 절대 데이터 디렉터리를 사용한 로컬 체크아웃 로딩을 다룹니다.

제로 지식(Zero-knowledge) 설정: docs/SETUP_PROMPT.md에서 프롬프트를 복사하여 AI 클라이언트에 붙여넣으면, 계정 설정을 위해 설치하고, 등록하며, 검증하고, 인터뷰를 진행합니다.

x-use init # 대화형(interactive) 설정 마법사
x-use run # 모든 활성 계정, 동시 실행
x-use run --account my_account # 단일 계정만 실행
...

--pipeline을 위한 파이프라인:

: community_engagement

, competitor_reposts

, content_curation

, keyword_replies

, keyword_retweets

, likes.

MCP의 run_cycle 도구는 동일한 이름을 받습니다.

레거시(legacy) 진입점인 python src/main.py는 사용 중단된 호환성 슁(shim)을 통해 계속 사용할 수 있습니다. 레거시 배치 엔진에는 x-use run을 사용하십시오.

x-use |
API 기반 X/Twitter MCP 서버 | |
|---|---|---|
| X API 비용 | $0: 쿠키 인증, X API 키 불필요 | 유료 X API 등급 필요 |
| 다중 계정 | 내장 기능: 계정별 설정, 쿠키, 프록시 | 일반적으로 단일 계정 |
| 프록시 | 계정별 프록시, 이름 지정 풀(named pools), 해시/라운드 로빈 순환 | 해당 없음 (N/A) |
| 브라우저 관리 | 격리된 Chromium 컨텍스트, 계정별 직렬화, 크로스 프로세스 소유 잠금 | 해당 없음 (공식 API) |
| 작성 안전성 | 기본적으로 초안 모드(Draft mode), 명시적인 approve_draft 게이트 | 보통 바로 게시함 |
| 메트릭 | 계정별 카운터 + JSONL 이벤트 로그, MCP를 통해 읽기 가능 | 다양함 (Varies) |

LLM 키는 선택 사항입니다: 대화형 MCP 사용에는 필요하지 않습니다(사용자 에이전트가 텍스트 작성). "auto" 생성을 위한 경우, 하나의 OpenAI 호환 키(llm.api_key + base_url + model) 또는 OPENAI_API_KEY/OPENAI_BASE_URL/OPENAI_MODEL을 설정해야 합니다. 이것이 유일하게 관련된 키입니다.

config/accounts.json: 사용자의 계정 목록 (gitignored). config/accounts.example.json에서 시작하거나 x-use init을 실행하여 작성하도록 할 수 있습니다.
config/settings.json: 브라우저, 페이싱(pacing), 액션 제한(action caps), LLM, 프록시 및 mcp에 대한 전역 기본 설정입니다.