# twscrape Twitter/X (read-only)

> twscrape Twitter/X (read-only) is an open-source MCP server for web search and scraping. Read X/Twitter posts, threads, replies and search results using your own logged-in session. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Windows, Linux
- **Repository:** https://github.com/jsilets/twscrape-twitter-mcp
- **MCP Registry name:** io.github.jsilets/twscrape-twitter-mcp
- **Categories:** [web search and scraping](https://ai-powered.com/categories/web-search-and-scraping), [news and media](https://ai-powered.com/categories/news-and-media)
- **Listing updated:** 2026-11-18

## About

Instead of the paid X API, this server wraps the twscrape library and reads X through a session you supply, so no developer account is needed. Results come back as markdown shaped for an agent, including image, video and GIF URLs and any external links in a post. Seven tools cover single posts, threads with the author's self-thread and top replies, replies, quote tweets, a user's timeline, search and user profiles.

Sign-in is a one-time step. The recommended path launches a dedicated Chrome or Brave profile where you log in to X and the session is captured; alternatives attach to an existing debug-enabled profile or take auth_token and ct0 cookies through hidden prompts for headless setups. The README advises burner accounts and notes extra sessions can be added to rotate around rate limits.

It runs locally over stdio, or as a hosted Streamable HTTP instance deployed in a container on Fly.io or Railway behind a bearer token. The README is upfront about limits: X can expire, rate-limit or suspend the session's account, restricted posts may not load, quote coverage is incomplete, and scraping with your own session may violate X's terms. It is licensed MIT.

## Features

- **Post and thread reading:** Returns a post, or a thread with the author's self-thread and top replies, as markdown.
- **Replies and quotes:** Lists replies to a post and, best-effort, its quote tweets.
- **Search operators:** Search supports operators such as from:, has:media and min_faves:.
- **Timelines and profiles:** Fetches a user's recent posts and a profile with bio, location and counts.
- **No paid API:** Uses your own X session through twscrape rather than the X API.
- **Two transports:** Runs over local stdio or hosted Streamable HTTP with a bearer token.

## Good for

- Have an agent summarise a long X thread
- Collect replies to a post for sentiment review
- Search X with operators for posts with media and many likes
- Check a user's recent posts and profile details
- Run a private always-on X reader for a team

## Install

### Claude Code (Terminal)

```sh
claude mcp add twscrape-twitter-mcp -- uvx twscrape-twitter-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "twscrape-twitter-mcp": {
      "command": "uvx",
      "args": [
        "twscrape-twitter-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "twscrape-twitter-mcp": {
      "command": "uvx",
      "args": [
        "twscrape-twitter-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "twscrape-twitter-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "twscrape-twitter-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "twscrape-twitter-mcp": {
      "command": "uvx",
      "args": [
        "twscrape-twitter-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "twscrape-twitter-mcp": {
      "command": "uvx",
      "args": [
        "twscrape-twitter-mcp"
      ]
    }
  }
}
```

## Tools

- `read_tweet`: Returns one post as markdown.
- `read_thread`: Returns the root post, the author's self-thread and top replies.
- `read_replies`: Returns replies to a post.
- `read_quotes`: Returns quote tweets, best-effort and search-based.
- `user_timeline`: Returns a user's recent posts, optionally with replies.
- `search`: Searches X with operators such as from: and has:media.
- `user_profile`: Returns a profile with bio, location, counts and join date.

## FAQ

### Do I need an X API key?

No. It reads with your own logged-in X session through twscrape.

### How do I log in?

Run login --launch-browser chrome (or brave) to sign in once in a dedicated profile, attach to a debug-port profile, or add auth_token and ct0 cookies with the init command.

### Is it safe to use my main account?

The README recommends burner accounts, because scraping may violate X's terms and the account can be rate-limited or suspended.

### How do I host it remotely?

Deploy the container on Fly.io or Railway and set TWSCRAPE_TWITTER_MCP_AUTH_TOKEN; clients send it as a bearer token.

### What are the known gaps?

Protected or deleted posts may not be readable, and quote coverage is search-based and incomplete.

### Is twscrape Twitter/X (read-only) free?

Yes. twscrape Twitter/X (read-only) is open source, so you can use and self-host it for free.

### How do I add twscrape Twitter/X (read-only) to Claude Code?

Run this command in your terminal: claude mcp add twscrape-twitter-mcp -- uvx twscrape-twitter-mcp

### What are the best alternatives to twscrape Twitter/X (read-only)?

The closest alternatives to twscrape Twitter/X (read-only) are Scrapling MCP Server, TrendRadar, Firecrawl MCP Server, Douyin_TikTok_Download_API and SearXNG Search.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [TrendRadar](https://ai-powered.com/mcp/trendradar): TrendRadar is an open-source MCP server for communication.
- [Firecrawl MCP Server](https://ai-powered.com/mcp/firecrawl-mcp-server): Firecrawl MCP Server is a freemium MCP server for web search and scraping.
- [Douyin_TikTok_Download_API](https://ai-powered.com/mcp/douyin-tiktok-download-api): Douyin_TikTok_Download_API is an open-source MCP server for web search and scraping.
- [SearXNG Search](https://ai-powered.com/mcp/searxng-search): SearXNG Search is an open-source MCP server for web search and scraping.
- [machine_internet](https://ai-powered.com/mcp/machine-internet): machine_internet is an open-source MCP server for web search and scraping.
- [acrawl](https://ai-powered.com/mcp/acrawl): acrawl is an open-source MCP server for browser automation.
- [Design Feeds](https://ai-powered.com/mcp/design-feeds): Design Feeds is a freemium MCP server for design and media.

---
Source: https://ai-powered.com/mcp/twscrape-twitter-x-read-only
