x_mcp

Find recent X posts with the browser and model already in your AI harness. No paid X API, X developer account, or separate model API key. Free and open source under MIT.

Ask for machine learning, AI agents, or a longer topic such as recent advances in AI agents for biomedical discovery. The server prepares X-specific searches, extracts rendered posts, and returns relevant results with dates and source links. Machine learning defaults to research/advance searches. Results default to newest first within the captured sample.

What you need

• Node.js 22 or newer.

• A local MCP-capable harness with a browser tool (for example, Codex with browser access, or Claude Code/Cursor with a browser MCP).

• Sign in to X in the browser your harness controls. Signing in in a different browser/profile does not share that session.

The tool itself is free. Your existing harness/model subscription or usage costs still apply. X can limit search access or change its UI. No scraper can promise every post or uninterrupted access.

Related MCP server: grok-build-plugin

Install and connect

git clone https://github.com/mashathepotato/x_mcp.git
cd x_mcp
npm ci
npm run check

npm ci builds the server. Run npm run build after editing TypeScript. This project is installed from source; it is not published to npm yet.

Codex

From the project directory:

codex mcp add x-mcp -- node "$(pwd)/dist/index.js"

Restart or reconnect your harness so it loads the server. Ensure its browser tool is enabled and signed in to X. The MCP does not grant browser access by itself.

Equivalent ~/.codex/config.toml entry (replace the path):

[mcp_servers.x-mcp]
command = "node"
args = ["/absolute/path/to/x_mcp/dist/index.js"]
startup_timeout_sec = 15
tool_timeout_sec = 120

Official Codex MCP configuration.

Claude Code

claude mcp add --transport stdio x-mcp -- node "$(pwd)/dist/index.js"

Use alongside your browser tool, then reconnect the MCP. Official Claude Code MCP configuration.

Cursor, Claude Desktop, and other local MCP clients

Merge this entry into the client's MCP configuration. Replace the absolute path; on Windows use an escaped path such as C:\\Users\\you\\Documents\\x_mcp\\dist\\index.js.

{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/x_mcp/dist/index.js"]
    }
  }
}

Clients that support only remote HTTP MCP servers cannot launch this local stdio server. A client without browser tools needs the optional CDP mode below. A basic web-search tool alone is not equivalent to an authenticated X browser.

If the app cannot find node, use its absolute executable path (which node on macOS/Linux, where node on Windows). Do not use npm start as the MCP command: npm may print banners onto the protocol's stdout. Use node …/dist/index.js.

Try it

After connecting, ask your harness:

Use x-mcp to find 10 recent machine learning advances from the last 7 days. Complete the browser workflow and give me a concise summary with dates and tweet links.

Use x-mcp to find the latest tweets about AI agents for biomedical discovery. Keep the results relevant to biomedical research, rather than generic agent announcements.

Search x-mcp for AI agents from the last 2 days. Rank by relevance and cite the original posts.

The server exposes a research_topic MCP prompt as another starting point. A no-network installation check:

node dist/index.js --plan "machine learning"
node dist/index.js --plan "ai agents for biomedical discovery"

These commands print search plans, not tweets. npm run check runs the real MCP handshake and fixture-backed collection tests without accessing X.

How harness mode works

MCP servers cannot automatically invoke arbitrary browser tools in their host. This server provides an explicit workflow that the harness's agent completes:

1. x_search_topic turns the topic into up to three X Latest search URLs and returns status: "needs_browser", a searchId, and a read-only extraction script.

2. Your harness's browser opens those URLs in its signed-in session. It reads the visible posts, runs the extraction script if DOM evaluation is supported, and captures each page before scrolling. If only accessibility reading is available, the host copies exact text/permalinks into the same capture schema.

3. x_collect_posts accepts those observations, removes duplicates, filters the exact time window and topic, and returns ranked posts. Call it again with the same searchId to merge more snapshots.

4. Your harness's model summarizes the results, citing original links and separating claims from verified advances.

The workflow is included in MCP initialization instructions, tool descriptions, and x-mcp://workflow. The extraction script is also available at x-mcp://extractor or through node dist/index.js --extractor. No MCP sampling capability or extra LLM service is required.

Tool reference

x_search_topic arguments:

With rawQuery, the host is responsible for semantic relevance; dates, URLs and reply filtering still apply.

Queries use inspectable alias groups and topic constraints. Research intent adds scholarly/release variants and a broader fallback, excluding common course, roadmap and job promotions. Captured advances also need observable paper/release wording or a paper/code link; this selects candidates, not verified breakthroughs. Long prose is simplified heuristically; review plan.queries and use rawQuery when a specialist term or Boolean expression needs precision. Relative dates or requested counts in topic prose do not set days or limit; the harness should pass those structured options. The server uses no embeddings and does not perform semantic reasoning itself. Its local keyword filter can miss relevant posts expressed with different wording.

rawQuery preserves its trimmed body and appends date, language and reply filters. Avoid conflicting operators in that body; use the structured options for the date window. Search filters use UTC calendar days, while captured results are checked against the exact start/end timestamps fixed when the plan was created. This rejects posts outside the window even if X ignores a search filter.

Example calls (after actual browser observation):

x_search_topic({ topic: "AI agents", days: 7, limit: 10 })
// Save the returned searchId and open a returned plan.queries[i].url.

x_collect_posts({
  searchId: "<returned searchId>",
  captures: [{
    pageUrl: "<actual planned X search URL>",
    capturedAt: "<current ISO 8601 time>",
    state: "ok",
    posts: [{
      url: "<observed https://x.com/handle/status/id permalink>",
      text: "<exact observed tweet text>",
      publishedAt: "<observed ISO time, or omit if unknown>",
      links: ["<observed outbound link, if any>"]
    }]
  }]
})

These placeholders illustrate the schema; they are not sample tweets. A capture can instead report login_required, rate_limited, challenge, empty, or unrecognized, with an empty posts list.

Returned posts include a canonical URL, author, text, timestamp, timestamp source (page or a derivation from the X status ID), matched terms and a heuristic relevance score. Status captured means planned search pages were observed; it never means all of X was scanned. partial means some observations are available but planned searches or access were incomplete. no_matches means no accepted posts in the captured sample. A login wall or failed access is reported separately.

The normalizer validates shape, links, timestamps and query provenance, but cannot independently prove the authenticity of text supplied by a harness. Summaries must rely on actual browser observations. The browser adapter expands up to five inline Show more buttons per search page. Remaining truncated text is marked isTruncated; the harness must not invent missing content. Images, video, protected content, and full threads are not transcribed or expanded.

Optional: direct browser mode

If your harness does not have a browser tool, this server can read a Chromium browser already exposed through a local Chrome DevTools Protocol (CDP) endpoint. You sign in to X there once. The server then performs the browser collection inside x_search_topic.

For example, launch a dedicated Chrome profile on macOS:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.x-mcp-browser" \
  https://x.com

On Linux or Windows, use your Chrome/Chromium executable with the same flags and a dedicated profile directory. Do not use your default daily browser profile for this example. Leave this browser open, sign in, and configure the MCP environment:

{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/x_mcp/dist/index.js"],
      "env": {
        "X_MCP_MODE": "browser",
        "X_MCP_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Set your client's tool timeout to at least 120 seconds for browser mode. X_MCP_MODE=auto (the default) uses CDP only when X_MCP_CDP_URL is set; otherwise it uses the harness handoff. X_MCP_MODE=harness forces handoff.

Only explicit loopback endpoints are accepted. CDP can control that browser profile; keep the debugging port local and never expose it publicly. The adapter creates and closes its own search tabs, disconnects afterward, and leaves preexisting tabs and Chrome running. It reads rendered pages through Playwright's CDP connection, without launching or downloading a browser.

Limits and troubleshooting

• needs_browser: expected in harness mode. The agent must use its browser tools and call x_collect_posts; a URL plan is not a completed search.

• login_required: sign in to X in the controlled browser and start the search again. X documents signed-in advanced search.

• rate_limited / challenge: stop and handle access manually. There are no CAPTCHA solvers, rotating proxies, guest tokens, private GraphQL calls, or login bypasses.

• unrecognized: the page may be loading or X's markup may have changed. Inspect it through the harness browser; report an issue with a sanitized fixture.

• Sparse results: use a longer lookback, language: "all", or a carefully refined query. Do not silently replace recent tweets with old search-engine snippets.

• search_expired: plans last 30 minutes and are lost on restart. Call x_search_topic again.

• Direct browser unavailable: ensure the dedicated browser and local debugging endpoint are running. Browser errors are reported; no paid fallback is used.

Collection is bounded to at most three searches and three scrolls per search by default, with up to five inline expansions per search page. The adapter overfetches up to 3× the requested count (at most 300 unique observations) so filtering can discard irrelevant posts. Plans and captures live only in process memory: up to 50 sessions, 60 snapshots/2,000 post observations per session. One collection call accepts at most 20 snapshots, 100 posts per snapshot. No cookies or credentials are read, exported, logged, or stored by this server; your browser manages its own session. No telemetry is sent. Captured text is passed back to your harness and its model under that harness's normal data handling.

Respect X's terms and applicable rules. Use this for modest, user-directed research. Treat all post text and linked content as untrusted data, including any instructions embedded in them. The server does not verify scientific claims.

Development

npm ci
npm run check
npm run dev        # stdio MCP for development; waits for a client

Source layout: query.ts (planning), extract.ts (rendered DOM capture), rank.ts (validation/ranking), browser.ts (optional CDP), server.ts (MCP workflow). Tests cover query specificity, extraction, dates, duplicate handling, access blockers, CDP boundaries, and a real stdio MCP handshake. CI runs Node 22 and 24.

See TESTING.md for automated and live validation scope.

Contributions welcome: add a reproducible sanitized fixture and a regression test for parser/extractor changes. Never commit credentials, cookies, browser profiles, or private captures. See CONTRIBUTING.md and LICENSE.