# X (Twitter) MCP Server (`seemuapps/x-mcp`) Actor

MCP server exposing X / Twitter scraping tools. Profile, followers, tweets, replies, search. For any AI agent or LLM client.

- **URL**: https://apify.com/seemuapps/x-mcp.md
- **Developed by:** [Andrew](https://apify.com/seemuapps) (community)
- **Categories:** MCP servers, Social media, Lead generation
- **Stats:** 6 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.00005 / actor start

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## X (Twitter) MCP Server

The all-in-one MCP server for X (Twitter). Plug any AI agent — Claude, Cursor, ChatGPT, VS Code, or your own — into a single endpoint and pull live data from any public X account: profile, followers, tweets, replies, and keyword search.

### What you get

- **Full profile metadata** — user ID, display name, bio, follower/following/tweet counts, blue verification, location, website, profile picture, and banner
- **Followers list** — paginated, with username, display name, bio, blue verification, follower counts, and profile picture for every account
- **User timeline** — most recent tweets from any public user, with full engagement counts (likes, retweets, replies, quotes, views, bookmarks) and quote/retweet relationships
- **Replies to a tweet** — every reply on a thread, sorted by Likes / Latest / Relevance, with author and engagement data
- **Keyword search** — search public tweets with X advanced search operators (`from:`, `since:`, `until:`, `lang:`, `min_faves:`, etc.)
- **One endpoint, five tools** — no glue code, no per-tool integrations, no scraping infrastructure to maintain

### Use cases

- AI agents and assistants that need X data without building a custom scraper
- Brand monitoring and social listening — track mentions, replies, and sentiment in real time
- Lead generation and account vetting — pull bio, follower counts, and engagement signals in bulk
- Influencer discovery and outreach — search by topic, then enrich profiles
- Competitor monitoring — follow tweet activity, audience growth, and reply threads
- Trend research and news tracking with keyword + advanced search operators

### Tools exposed

| Tool             | Returns                                                                  |
|------------------|--------------------------------------------------------------------------|
| `get-profile`    | Profile metadata for up to 20 usernames per call                         |
| `get-followers`  | Paginated follower list for a username                                   |
| `get-tweets`     | Paginated user timeline (most recent tweets) for a username              |
| `get-replies`    | Paginated replies to a specific tweet                                    |
| `search-tweets`  | Paginated keyword / advanced-search results                              |

### How to use

Use Apify's hosted MCP gateway — it generates ready-to-paste config snippets for Claude Desktop, Cursor, VS Code, ChatGPT, and any other MCP-compatible client:

**[mcp.apify.com/?tools=seemuapps/x-mcp](https://mcp.apify.com/?tools=seemuapps/x-mcp)**

Open the link, sign in, and copy the snippet for your client.

#### Where to get your Apify API token

Go to **[console.apify.com/settings/integrations](https://console.apify.com/settings/integrations)** and copy your **Personal API token**. (Sign in or create a free account if you haven't already.)

The token authorizes calls to the MCP server and is what Apify uses to bill you for tool calls.

### Pricing (pay-per-event)

| Tool             | Event             | Charged                                              |
|------------------|-------------------|------------------------------------------------------|
| `get-profile`    | `profile-lookup`  | Once per profile successfully returned               |
| `get-followers`  | `user-result`     | Once per follower returned                           |
| `get-tweets`     | `tweet-result`    | Once per tweet returned                              |
| `get-replies`    | `reply-result`    | Once per reply returned                              |
| `search-tweets`  | `tweet-result`    | Once per tweet returned                              |

Failed calls are not charged. Partial failures (e.g. one bad username in a batch) are reported per-item without aborting the whole call.

### Pagination

`get-followers`, `get-tweets`, `get-replies`, and `search-tweets` all accept `maxItems` (default 200) and an optional `pageId` cursor. Each response includes a `nextPageId` — pass it as `pageId` on the next call to fetch the following page. When `nextPageId` is `null`, the list is exhausted.

```json
{
  "tweets": [ { "tweetId": "...", "text": "...", ... } ],
  "nextPageId": "DAABCgABG..."
}
```

When running a tool directly (without an MCP client), the cursor is also written to the run's **Key-value store** under the `NEXT_PAGE_ID` key for easy chaining across runs.

### Notes

- Only **public** X accounts and tweets are supported. Protected accounts return profile metadata only.
- Usernames are accepted with or without leading `@`, and full `https://x.com/<user>` URLs are also recognised.
- For `get-replies`, the default sort order is `Likes` — `Relevance` often returns very few results, and `Latest` is reverse-chronological.
- For `search-tweets`, see X's advanced search operator reference for the full query syntax.

### Related X (Twitter) actors

Part of a complete X (Twitter) toolkit — explore the rest of the suite:

- [X (Twitter) Profile Scraper](https://apify.com/seemuapps/x-profile-scraper) — Public profile data — bio, counts, links
- [X (Twitter) User Tweets Scraper](https://apify.com/seemuapps/x-user-tweets-by-username) — Full timeline of any account by username
- [X (Twitter) Tweet Scraper](https://apify.com/seemuapps/x-tweet-scraper) — Search and export tweets by query, hashtag, user
- [X (Twitter) Tweet Replies Scraper](https://apify.com/seemuapps/x-tweet-replies-scraper) — Every reply under a post for sentiment analysis
- [X (Twitter) Quote Tweets Scraper](https://apify.com/seemuapps/x-quote-tweets-scraper) — Every quote tweet of a post with engagement
- [X (Twitter) Followers & Following Scraper](https://apify.com/seemuapps/x-followers-following-scraper) — Full followers and following lists, no login
- [X (Twitter) List Members Scraper](https://apify.com/seemuapps/x-list-members-scraper) — Members or followers of any public list
- [X (Twitter) Active Hours Analyzer](https://apify.com/seemuapps/x-active-hours-analyzer) — Posting heatmap, peak hours, and time zone

# Actor input Schema

## `tool` (type: `string`):

Pick a tool to run and save results to the dataset, or leave empty to start the actor as an MCP Standby server.

## `username` (type: `string`):

Single X username (with or without leading @) — required by get-followers and get-tweets.

## `usernames` (type: `array`):

X usernames — required by get-profile (1–20).

## `tweetId` (type: `string`):

Numeric tweet ID or full https://x.com/<user>/status/<id> URL — required by get-replies.

## `query` (type: `string`):

Search query — required by search-tweets. Supports X advanced search operators (from:, since:, lang:, etc.).

## `maxItems` (type: `integer`):

Max items returned by paginated tools (get-followers, get-tweets, get-replies, search-tweets).

## `pageId` (type: `string`):

Cursor for paginated tools. Paste nextPageId from a previous run to continue.

## Actor input object example

```json
{
  "tool": "",
  "username": "elonmusk",
  "usernames": [
    "elonmusk"
  ],
  "maxItems": 200
}
```

# Actor output Schema

## `results` (type: `string`):

Records produced by the selected tool: profiles (get-profile), users (get-followers), or tweets (get-tweets, get-replies, search-tweets). One record per row.

## `nextPageId` (type: `string`):

NEXT\_PAGE\_ID record in the default key-value store. Paste into Page ID on the next run to fetch the next page; null when the list is exhausted. Set by get-followers, get-tweets, get-replies, and search-tweets.

## `keyValueStore` (type: `string`):

Profile pictures saved by get-profile (one entry per profile, returned as profilePicStorageUrl in each record).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "username": "elonmusk",
    "usernames": [
        "elonmusk"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("seemuapps/x-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "username": "elonmusk",
    "usernames": ["elonmusk"],
}

# Run the Actor and wait for it to finish
run = client.actor("seemuapps/x-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "username": "elonmusk",
  "usernames": [
    "elonmusk"
  ]
}' |
apify call seemuapps/x-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=seemuapps/x-mcp",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/LXFolWHZBEXF0SeL3/builds/qFp6zIj16dDS7WqsA/openapi.json