xarticle-mcp

Save an X (Twitter) Article to disk as Obsidian-faithful Markdown — with images and videos downloaded locally — so it reads in Obsidian the way it reads on X.

One tool: xarticle <url> → creates <slug>/<slug>.md + images/ (+ media/ for video) in your working directory, with YAML frontmatter and local, rewritten links.

Works in any MCP client: Claude Code, Codex, Cursor, Windsurf, … It fetches with your own X session, stored encrypted on your machine.

Requirements

• Node.js ≥ 18

• Google Chrome or Microsoft Edge installed (Edge ships with Windows). The tool drives your existing browser — no separate browser download.

Related MCP server: riocloud-reader

Install (one line)

Add this to your MCP client config:

{
  "mcpServers": {
    "xarticle": { "command": "npx", "args": ["-y", "xarticle-mcp"] }
  }
}

• Claude Code — .mcp.json in your project root (or your user MCP config).

• Codex — add an MCP server entry with the same command + args.

• Cursor / Windsurf / others — same command + args in their MCP settings.

Prefer running straight from source? Use "args": ["-y", "github:aniirude/xarticle-mcp"].

macOS/Linux use the same config. The tool uses your installed Chrome/Edge; nothing else to install.

One-time login (paste 2 cookies)

X Articles need your logged-in session. There's no automated login (X rate-limits those), so you paste two session cookies once — they're stored encrypted at ~/.xarticle/.

npx -y xarticle-mcp login

It walks you through it:

1. In a browser logged into X, press F12.

2. Application tab (Chrome/Edge) or Storage (Firefox) → Cookies → https://x.com.

3. Copy the value of auth_token, paste, Enter.

4. Copy the value of ct0, paste, Enter.

Check it anytime with npx -y xarticle-mcp status.

Alternative (no DevTools): npx -y xarticle-mcp login --browser reuses your real Chrome profile — but you must fully quit Chrome first (it can be flaky on Windows).

Use

In your MCP client, ask:

xarticle https://x.com/<user>/status/<id>

It writes, in your current working directory:

<article-slug>/
  <article-slug>.md     # frontmatter + body, local links
  images/               # 01.jpg, 02.jpg, …  (+ cover)
  media/                # <slug>-01.mp4, …   (videos, when downloadable)

• Saves to the directory your MCP client is running in. Pass outputDir to override.

• Videos with a direct MP4 are embedded as ![[…mp4]] (Obsidian renders a player). Stream-only (HLS) videos fall back to a poster image + a link to X.

Tool input

CLI (handy for testing)

npx -y xarticle-mcp save <url> [outputDir]   # fetch without an MCP client
npx -y xarticle-mcp status                    # check the saved session

Notes & caveats

• Personal use. This automates access with your own session; keep it low-volume. Respect X's Terms.

• Only what you can see. Articles your account can't view won't fetch.

• Obsidian video embeds (![[…mp4]]) render inside an Obsidian vault.

• X changes its markup. All X-DOM selectors live in src/fetchArticle.ts — the one file to update if extraction drifts.

Develop

npm install
npm run build
npm run smoke   # offline: markdown/video conversion + tools/list

MIT © aniirude