# x-reader [Health: Active]

**Category:** 🔎 Search & Data Extraction  
**Repository:** https://github.com/runesleo/x-reader  
**GitHub Stars:** 988  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/x-reader

## Description
Universal content reader MCP Server for 10+ platforms

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "x-reader": {
    "command": "uvx",
    "args": ["yt-dlp"]
  }
}
```

## Documentation

## What x-reader MCP server does

x-reader MCP server gives an AI agent a URL-oriented reading workflow for more than ten source types. It handles X/Twitter posts, web pages and articles, YouTube, Bilibili, WeChat, Xiaohongshu, Telegram, RSS, Xiaoyuzhou, Apple Podcasts, and other open-web URLs. Retrieved material is normalized into structured source content for research, summarization, and automation.

Its defining behavior is evidence tracking. A search result, post caption, video title, or description is treated as a limited layer rather than proof that the underlying source was read. The result can be marked `PASS`, `PARTIAL`, `FAIL`, or `UNKNOWN` depending on source access, media coverage, and verification.

## How it works

The reader chooses a source-specific path. X/Twitter uses oEmbed, FxTwitter, article or Jina retrieval, and Playwright where applicable. Web pages use a pinned direct read that checks redirects and embedded audio or video before falling back to Jina Reader text. YouTube uses yt-dlp metadata and subtitles, with an optional Groq Whisper fallback. Other platforms use their respective APIs, browser workflows, feed parsing, Telethon, or episode-page extraction.

When a URL redirects to a recognized platform, x-reader passes it to that platform's reader. The Agent Skill can also inspect attached media with local tools. For example, X post text may be readable while an attached video remains `PARTIAL` until its relevant spoken or visual content is handled. Subtitle coverage can provide spoken-content evidence, but it does not establish that the video's images were analyzed.

The command-line path supports URL reading and JSON output through `x-reader URL --json`. The read-only `x-reader doctor` command performs a local self-check. A separate `x-reader-web` surface projects the same result into an evidence receipt for public X, YouTube, and generic web URLs.

## Setup and configuration

The project requires Python 3.10 or newer. Its plugin starts the MCP server with `uvx`, so `uv` must be installed. The bundled Agent Skill can be installed with:

```bash
npx skills add runesleo/x-reader --skill x-reader
```

The repository also supports plugin installation for Claude Code, Codex, and Cursor. Optional source workflows require additional local setup. Telegram reading needs Telegram credentials; Xiaohongshu may require a one-time local login; transcription can use the opt-in local ASR workflow or the Groq fallback when configured.

To run the local evidence web surface, install the project and start `x-reader-web`, for example:

```bash
pip install -e .
x-reader-web --host 127.0.0.1 --port 8787
```

## Tools and capabilities

- Read public and source-specific URLs through an MCP-connected agent workflow.
- Extract article and web-page text, X post content, RSS entries, podcast notes, subtitles, and platform metadata.
- Handle audio or video completion paths where the required local tools, credentials, or transcription settings are available.
- Return machine-readable JSON and evidence receipts.
- Report `PASS`, `PARTIAL`, `FAIL`, or `UNKNOWN` states.
- Run a read-only environment check with `x-reader doctor`.

## Limitations and notes

Access and coverage vary by platform and can change over time. Login walls, deleted pages, paywalls, cookie walls, empty responses, and incomplete media can produce `PARTIAL`, `FAIL`, or `UNKNOWN` rather than a completed read. Public WeChat articles use browser fallback, while saved login sessions are not used. The hosted evidence-receipt beta accepts public X/Twitter, YouTube, and generic web URLs and uses an isolated temporary environment without saved browser sessions, Telegram credentials, Groq keys, Obsidian paths, or external X cookies.

Retrieved pages, posts, transcripts, subtitles, metadata, and comments should be treated as untrusted data rather than agent instructions. The evidence contract also distinguishes spoken-content coverage from visual analysis: reading subtitles does not mean the video images were examined.

_Full upstream README: https://allmcps.com/mcp/x-reader/readme_