github.com/nirholas/xactions
X
X / Twitter automation toolkit

XActions
操作手冊

XActions 將 X/Twitter 的公開資料讀取、帳號操作與分析整合為 CLI、Node.js、MCP、瀏覽器腳本及擴充套件。先用免登入讀取驗證環境，再依任務需求啟用登入與寫入權限。

152
MCP tools
20+
Node.js
5
主要介面
Apache
2.0 license
01
工具定位

XActions 的執行模型

XActions 是 X/Twitter 自動化工具組。公開 profile 與 timeline 可由 CLI 直接讀取；搜尋、followers、DM 與寫入操作需要登入工作階段。

同一組能力可由終端機、Node.js、MCP client、瀏覽器 console 或 browser extension 呼叫。依執行環境選擇入口，不必同時安裝全部介面。

核心流程
公開讀取→登入驗證→限制工具群組→核准寫入→輸出紀錄
Your x.com tab does all the work. Nothing gets scraped to our servers. You're in control.
— XActions README
02
安裝與首次驗證

從免登入讀取開始

直接執行

npx xactions profile nasa

專案依賴

npm install xactions

全域 CLI

npm install -g xactions xactions quickstart

Docker

docker build -t xactions . docker run -it xactions xactions profile elonmusk
執行需求

原始碼開發需要 Node.js 20 或更新版本。先執行 node -v；公開 profile 測試不需要帳號或 Cookie。

03
能力總覽

五種操作入口

CLI
xactions
終端機工作流
執行 profile、tweets、search、download、report、login 與設定指令。
MCP
xactions-mcp
AI agent 工具層
向 Claude、GPT、Cursor 等 MCP client 提供分組工具與核准式寫入。
SDK
import xactions
Node.js 整合
把 scraper、登入與自動化函式嵌入應用程式或批次流程。
Browser
console scripts
頁面內操作
在已登入的 x.com 分頁執行單一用途腳本。
Extension
Manifest V3
瀏覽器介面
從 Chrome 或 Firefox popup 啟動自動化，不需貼入 console。
任務建議入口原因
一次性讀取與匯出CLI可直接輸出 JSON、CSV 或檔案
AI agent 查詢與操作MCP可限制工具群組並啟用核准閘
應用程式內整合Node.js可組合函式與錯誤處理
頁面內單次操作browser script沿用目前分頁與登入狀態
04
官方安全機制

寫入前的控制面

RULE 01

先限制 MCP 工具群組

以 --tools read,analytics 僅公開讀取與分析工具；需要寫入時再擴大範圍。

來源 · 官方 README MCP
RULE 02

啟用人類核准閘

設定 XACTIONS_MCP_REQUIRE_APPROVAL=1，讓每次寫入在執行前等待核准。

來源 · 官方 README MCP
RULE 03

使用每日動作上限

MCP 寫入依帳號記錄 rolling 24-hour budget；超額呼叫會在送往 X 前拒絕。

來源 · 官方 README What's New
RULE 04

完整匯入 Cookie jar

login --from-browser 或 --cookies-file 可帶入包含 ct0 的完整工作階段。

來源 · 官方 README Login
RULE 05

以 JSON 建立可檢查輸出

讀取命令使用 --json，資料輸出至 stdout，便於 pipe、記錄與驗證。

來源 · 官方 README CLI
RULE 06

先執行 doctor

登入或瀏覽器流程失敗時先執行 xactions doctor，再依錯誤調整環境。

來源 · 官方 README CLI
05
使用實例

品牌提及的唯讀蒐集

以下流程先確認公開 profile，再登入並搜尋品牌提及。最後以 JSON 輸出供後續程式處理；全程不啟用寫入工具。

~/research · xactions
$ npx xactions profile nasa --json [public profile returned as JSON] $ npx xactions login --from-browser chrome [imports the selected browser session] $ npx xactions search "your brand" --limit 50 --json > mentions.json [stdout saved to mentions.json] $ npx xactions doctor [environment diagnostics complete]
Every read command accepts --json and puts data on stdout and nothing else.
— XActions README

驗收條件

mentions.json 可被 JSON parser 讀取，且流程沒有呼叫 follow、like、post、DM 或其他寫入動作。

06
限制與責任

帳號自動化的邊界

  • 平台規範仍然適用。官方 disclaimer 要求遵守 X 的 Terms of Service；大量或侵擾式自動化可能造成帳號限制。
  • 登入資料等同帳號權限。不要把 auth_token、ct0、Cookie export 或 storageState 提交到 Git、貼入報告或傳給未授權服務。
  • 公開讀取與寫入風險不同。先以 profile、tweets、report 等唯讀指令驗證；follow、unfollow、like、post 與 DM 必須另外核准。
  • 頁面 selector 可能改變。瀏覽器腳本依賴 x.com DOM；失敗時停止批次操作並檢查 selector，不要無限重試。
  • 內建延遲不等於免責。rate limiting 與每日上限是控制措施，不保證平台接受自動化行為。
  • 本機執行仍會處理敏感資料。限制檔案權限、清除不再使用的 session，並將寫入流程保留可稽核紀錄。
07
進階路徑

從 CLI 到受控整合

進階地圖

1. 固定唯讀基線。將 profile、tweets 與 --json 納入測試，保留可重跑的輸出格式。

2. 設定 MCP client。執行 npx xactions mcp-config --client claude 或對應 client；先只公開 read 與 analytics。

3. 加入寫入核准。啟用 XACTIONS_MCP_REQUIRE_APPROVAL=1，並為帳號設定可接受的每日動作範圍。

4. 封裝 Node.js 流程。在應用程式中加入錯誤處理、dry run、重試上限與執行紀錄。

5. 驗證文件同步。貢獻程式碼前執行專案測試與 npm run docs:check，避免文件中的指令或工具數量漂移。

延伸閱讀

① CLI reference
② MCP server
③ Security policy

Nothing reports empty results as success anymore.
— XActions README