Skip to main content
Glama
aniirude

xarticle-mcp

by aniirude
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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: news-dashboard

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

field

type

default

notes

url

string

—

the X Article/post URL

outputDir

string

working dir

where to create the folder

imageFormat

"original" | "png"

original

png re-encodes (needs sharp)

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

Available Tools

1 tool
xarticleSave X Article to MarkdownA

Fetch an X (Twitter) Article and save it as an Obsidian-faithful Markdown file with images and media downloaded locally. Creates /.md + images/ + media/ in the working directory (or outputDir). Requires a one-time xarticle-mcp login.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe X Article URL (x.com/...)
outputDirNoWhere to create the article folder. Defaults to the current working directory.
imageFormatNoImage format on disk. "original" (default) keeps jpg/webp; "png" re-encodes (needs sharp).

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool downloads media locally, creates a specific folder structure, and requires a prior login. It doesn't cover error behaviors or rate limits, but for a straightforward fetch tool, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—two sentences that cover all essential aspects: action, output details, and prerequisite. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 parameters, no output schema), the description is sufficiently complete. It explains what the tool does, what it produces, and what setup is needed. Minor omission: no mention of network dependency, but that is implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions. The description adds value by explaining the output directory default and the image format option, plus the file structure context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the action (fetch and save), the resource (X Article), and the output format (Obsidian-faithful Markdown with local media). It clearly states the file structure created, leaving no ambiguity about the tool's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mentions the prerequisite one-time login command, guiding the user on setup. It does not exclude any cases, but it is clear when the tool should be used. Without sibling tools, no alternative guidance needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedxarticle
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools.

Naming Consistency5/5

With a single tool, naming consistency is inherently perfect.

Tool Count4/5

For the narrow purpose of fetching X articles, a single tool is reasonable, though slightly limited in scope.

Completeness3/5

The tool handles fetch and save, but lacks operations like listing, deleting, or managing multiple articles, which could be useful.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers