x-media-mcp

Local MCP server for inspecting/downloading public media from X posts and building a durable, Agent-friendly index of your own saved posts.

Status

P0  public media pipeline       ✅
P1  saved-post synchronization  ✅
P2  provider reliability        ✅
P3  saved-post intelligence     ✅
P4  Agent-ready distribution    🟡

Install as an npm package

Requires Node.js 22.13 or newer.

Install the npm latest release globally:

npm install -g x-media-mcp@latest
x-media-mcp --version
x-media-mcp

Or let an Agent/MCP client resolve the current stable latest release without pinning a package version:

npx -y x-media-mcp@latest

A global installation is not self-updating. Run npm install -g x-media-mcp@latest again when you want to upgrade it. For Agent configurations that should follow the current stable release without editing a version number, prefer the npx ... @latest form.

GitHub v<package version> Releases also contain the exact installable npm tarball:

npm install -g ./x-media-mcp-<version>.tgz
x-media-mcp --version

Each package Release also links the current browser companion ZIP. The browser extension is independently versioned and is not rebuilt for every npm package release.

The npm launcher materializes the bundled MCP runtime under ~/.x-media-mcp, so SQLite data, downloads, exports and local bridge state live outside the npm installation and survive package upgrades.

Set X_MEDIA_MCP_HOME before launch if you want a different data root.

Add to an MCP client / Agent

For a fixed global npm installation:

{
  "mcpServers": {
    "x-media": {
      "command": "x-media-mcp"
    }
  }
}

For an Agent that should automatically resolve npm's stable latest dist-tag without changing the configuration on every release:

{
  "mcpServers": {
    "x-media": {
      "command": "npx",
      "args": ["-y", "x-media-mcp@latest"]
    }
  }
}

On Windows, some MCP clients require x-media-mcp.cmd / npx.cmd instead of the extensionless command. The packaged CLI is smoke-tested on Windows during CI.

See docs/npm-distribution.md for packaging, npm latest behavior, environment variables, proxy/debugging setup, Trusted Publishing and Agent installation details.

Proxy / debugging quick setup

If X media downloads fail with network errors such as ECONNRESET while the same media opens normally in a proxied browser, the currently verified debugging method is to configure the proxy in x-media-mcp's .env file.

For npm installations edit:

~/.x-media-mcp/.env

On Windows this is normally:

C:\Users\<you>\.x-media-mcp\.env

For a dedicated media proxy, put this in the file:

X_MEDIA_PROXY=http://127.0.0.1:7890

Or, if you want to use standard proxy settings, put them in the same .env file:

HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890
NO_PROXY=localhost,127.0.0.1

Replace 7890 with your proxy application's HTTP/Mixed port, then restart the MCP server / Inspector.

In the currently tested MCP Inspector / IDE debug launch path, setting HTTP_PROXY / HTTPS_PROXY or X_MEDIA_PROXY only in the parent PowerShell/process has not been reliable. Do not depend on parent-process proxy injection for debugging; use the .env file instead.

Keep localhost,127.0.0.1 out of external proxy routing because the local browser companion bridge is loopback-only.

Browser saved-post companion

The Chrome/Edge companion reads rendered numeric Post IDs from the signed-in X History/Bookmarks page and sends only those IDs to the paired loopback bridge. It does not read X cookies, auth_token, ct0, local-storage credentials or private X API responses, and browser synchronization never automatically downloads media.

The easiest distribution path is the Browser extension link in the newest v<package version> GitHub Release. That link points to the independently packaged browser-extension-v<extension version> Release, so package-only releases reuse the existing ZIP instead of rebuilding it.

After downloading the ZIP, extract it, enable developer mode in Chrome/Edge extensions, choose Load unpacked, and select the extracted directory. Then create a one-time pairing code with:

x_media_browser_pairing_code

See docs/browser-extension.md for the full install and pairing flow.

Saved-post tools

x_media_browser_bridge_status
x_media_browser_pairing_code
x_media_saved_sync_status
x_media_list_saved_posts
x_media_query_saved_posts
x_media_audit_saved_downloads
x_media_mark_saved_posts_processed
x_media_export_saved_posts
x_media_enrich_saved_posts
x_media_inspect_saved_posts
x_media_download_saved_posts

x_media_audit_saved_downloads is a local-only reconciliation view between the saved-post lifecycle and completed media downloads. Its views distinguish:

downloaded_not_saved   downloaded, but not currently active in the selected saved-post source
removed                previously saved, now removed; downloaded or not
downloaded_removed     previously saved, now removed, and media was downloaded
downloaded_never_saved downloaded locally but never observed in the selected saved-post source
all                    union of locally known saved and downloaded posts

The audit summary reports active/removed saved counts plus downloaded-active, downloaded-removed, downloaded-never-saved and total downloaded-not-saved counts. It never calls X or a Post provider. A removed state is only authoritative after a completed snapshot reconciliation from the browser companion or another source that records removals.

x_media_query_saved_posts and export selection are local-first. Explicit postIds can be handed from Agent reasoning to query/export/enrichment/inspect/download so side-effecting actions operate on the exact selected set rather than re-running fuzzy matching.

x_media_enrich_saved_posts, x_media_inspect_saved_posts and x_media_download_saved_posts are explicit remote actions. Per-Post failures are isolated.

Provider reliability

Public Post inspection/download is provider-agnostic. The provider layer supports ordered FxTwitter-compatible endpoints, transient retry, deterministic fallback and per-provider circuit breaking.

Use:

x_media_provider_status

See docs/provider-reliability.md for configuration.

Local data

For npm installations the default home is:

~/.x-media-mcp/
├─ .env                 optional
├─ data/
│  ├─ x-media.db
│  ├─ browser-bridge-token.json
│  └─ x-oauth-token.json   optional
├─ downloads/
├─ exports/
└─ apps/mcp/dist/       versioned bundled runtime

The optional official X OAuth integration remains separate from the browser-assisted saved-post flow.

Development

npm install
npm run build
npm test
npm run package:check

npm run package:check builds the standalone npm bundle and validates the publish file set with npm pack --dry-run.

See docs/roadmap.md for P4 distribution work.