# Twitter Mcp

> Free Twitter/X MCP server — search, post, read feed, trending — no API key needed. Playwright-based.

- **Type:** MCP server
- **Install:** `agentstack add mcp-miles0sage-twitter-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Miles0sage](https://agentstack.voostack.com/s/miles0sage)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Miles0sage](https://github.com/Miles0sage)
- **Source:** https://github.com/Miles0sage/twitter-mcp

## Install

```sh
agentstack add mcp-miles0sage-twitter-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Twitter/X MCP Server

**Read, search, and post on Twitter/X from any AI agent.** No API key needed -- uses persistent browser sessions.

[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](#tools)
[](https://github.com/Miles0sage/twitter-mcp)

---

## Why This Exists

Twitter's API costs $100+/month and rate-limits everything. This MCP server uses **Playwright browser automation** with a persistent Chrome profile instead -- zero API fees, no rate limit headaches. Your AI agent gets full Twitter access through the Model Context Protocol.

Works with Claude Code, Cursor, Windsurf, or any MCP-compatible client.

---

## Tools

| Category | Tool | Description | Auth Required |
|----------|------|-------------|:---:|
| **Read** | `twitter_search` | Search tweets by keyword or hashtag | No |
| | `twitter_feed` | Read your home timeline | Yes |
| | `twitter_bookmarks` | Read your saved bookmarks | Yes |
| | `twitter_user` | Get a user's profile info | No |
| | `twitter_user_tweets` | Get tweets from a specific user | No |
| | `twitter_trending` | Get trending topics | No |
| | `twitter_notifications` | Read your notifications | Yes |
| **Write** | `twitter_post` | Post a new tweet | Yes |
| | `twitter_reply` | Reply to a tweet | Yes |
| | `twitter_like` | Like a tweet | Yes |
| | `twitter_retweet` | Retweet a tweet | Yes |

> **No API key needed.** Read-only tools work without authentication. Write tools require a one-time browser login (cookies persist automatically).

---

## Quick Start

```bash
git clone https://github.com/Miles0sage/twitter-mcp.git
cd twitter-mcp
pip install -r requirements.txt
playwright install chromium
```

Add to your MCP config (`~/.mcp.json` or client settings):

```json
{
  "mcpServers": {
    "twitter": {
      "command": "python3",
      "args": ["server.py"],
      "cwd": "/path/to/twitter-mcp"
    }
  }
}
```

---

## Authentication

This server uses a **persistent Chrome profile** stored at `~/.twitter-mcp/chrome-profile/`. Log in once and your session persists across restarts.

### First-time setup

```bash
# Opens a real browser -- log in to Twitter/X manually
python3 -c "from browser_session import login; login()"
```

Once logged in, cookies are saved to the Chrome profile. All future MCP calls reuse the session automatically.

### Headless vs non-headless

Twitter blocks headless browsers. The server runs Chromium with `DISPLAY=:99` (Xvfb) by default for server environments. On desktop, it uses your normal display.

```bash
# Server/VPS setup
export DISPLAY=:99
Xvfb :99 -screen 0 1920x1080x24 &
```

### Keepalive

A keepalive script prevents session expiry by loading Twitter periodically:

```bash
# Add to crontab (every 30 min)
*/30 * * * * DISPLAY=:99 python3 /path/to/twitter-mcp/twitter_keepalive.py
```

---

## Usage Examples

```
"Search Twitter for AI agent news"
  -> Latest tweets matching query, with engagement stats

"Read my feed"
  -> Your home timeline, newest first

"Show my bookmarks"
  -> Your saved/bookmarked tweets

"Post: Just shipped a new MCP server!"
  -> Tweet posted, returns URL

"What's trending?"
  -> Top trending topics with tweet counts

"Get @elonmusk's recent tweets"
  -> Latest tweets from the user
```

---

## Architecture

```
LLM / MCP Client
       |
  MCP Protocol (stdio)
       |
  server.py ── registers 11 tools
       |
  +----+----+--------+
  |         |        |
tools_   tools_   tools_
read.py  feed.py  write.py
  |         |        |
  +----+----+--------+
       |
  browser_session.py
  (persistent Chromium via Playwright)
       |
  ~/.twitter-mcp/chrome-profile/
  (cookies + session state)
```

---

## Project Structure

```
server.py               # MCP server, tool registration
tools_read.py           # Search, user profile, user tweets, trending
tools_feed.py           # Feed, bookmarks, notifications
tools_write.py          # Post, reply, like, retweet
browser_session.py      # Playwright session management, persistent Chrome profile
twitter_keepalive.py    # Session keepalive cron script
api_server.py           # Optional REST API wrapper
```

---

## Comparison

| Feature | Twitter MCP | Twitter API (Basic) | Twitter API (Pro) | Apify Scrapers |
|---------|:-:|:-:|:-:|:-:|
| Cost | **Free** | $100/mo | $5,000/mo | Per-run fees |
| Auth | Browser login | OAuth + API key | OAuth + API key | API key |
| Post tweets | Yes | Yes | Yes | No |
| Read feed | Yes | Limited | Yes | Yes |
| Bookmarks | Yes | No | Yes | No |
| Search | Yes | Limited | Yes | Yes |
| Rate limits | Browser-level | Strict | Strict | Per-plan |
| MCP native | Yes | No | No | No |
| Setup time | 2 min | 30+ min | Application | 10 min |

---

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Miles0sage](https://github.com/Miles0sage)
- **Source:** [Miles0sage/twitter-mcp](https://github.com/Miles0sage/twitter-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-miles0sage-twitter-mcp
- Seller: https://agentstack.voostack.com/s/miles0sage
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.