# TwitterAPI.io MCP Server

TwitterAPI.io MCP is a Model Context Protocol server that provides AI assistants like Claude, Cursor, and VS Code Copilot with instant, offline access to TwitterAPI.io documentation. The server bundles a comprehensive documentation snapshot containing 67 active API endpoints with full HTTP methods, body/query parameters, cURL examples, and response schemas, along with 32 guide pages covering pricing, authentication, rate limits, and webhooks, plus 24 blog posts with tutorials and use cases.

Unlike other Twitter MCP servers that proxy live API calls and require an API key, this server operates entirely offline with zero network dependencies. The bundled documentation includes all current v2 endpoints (with deprecated v1 endpoints removed), making it a reliable reference for building Twitter/X integrations. The server features N-gram tokenization with fuzzy matching for typo-tolerant searches, hybrid caching (memory + disk) with 24-hour TTL, and structured output schemas optimized for LLM parsing.

## Installation

### Claude Code Installation

Installs the MCP server globally for all projects in Claude Code.

```bash
# Add globally (all projects)
claude mcp add --scope user twitterapi-io -- npx -y twitterapi-io-mcp

# Or project-only
claude mcp add twitterapi-io -- npx -y twitterapi-io-mcp

# Verify installation
claude mcp list
```

### Claude Desktop Configuration

Add the MCP server to Claude Desktop by editing the configuration file.

```json
{
  "mcpServers": {
    "twitterapi-io": {
      "command": "npx",
      "args": ["-y", "twitterapi-io-mcp"]
    }
  }
}
```

Config file locations:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Cursor Configuration

Add the MCP server to Cursor by creating `.cursor/mcp.json` in your project root.

```json
{
  "mcpServers": {
    "twitterapi-io": {
      "command": "npx",
      "args": ["-y", "twitterapi-io-mcp"]
    }
  }
}
```

### VS Code Configuration

Add the MCP server to VS Code by creating `.vscode/mcp.json` in your project root.

```json
{
  "servers": {
    "twitterapi-io": {
      "command": "npx",
      "args": ["-y", "twitterapi-io-mcp"]
    }
  }
}
```

### Docker Installation

Run the MCP server using Docker for containerized environments.

```bash
# Quick run
docker run -i --rm $(docker build -q .) 2>/dev/null

# Build from source
git clone https://github.com/dorukardahan/twitterapi-io-mcp.git
cd twitterapi-io-mcp && npm install
node index.js
```

## MCP Tools

### search_twitterapi_docs

Full-text search across all TwitterAPI.io documentation including endpoints, guides, and blog posts. Features fuzzy matching with typo tolerance and supports camelCase queries.

```json
{
  "tool": "search_twitterapi_docs",
  "arguments": {
    "query": "advanced search tweet",
    "max_results": 10
  }
}
```

Example response structure:
```json
{
  "query": "advanced search tweet",
  "max_results": 10,
  "cached": false,
  "counts": {
    "total": 5,
    "endpoints": 3,
    "pages": 1,
    "blogs": 1
  },
  "results": [
    {
      "type": "endpoint",
      "name": "tweet_advanced_search",
      "title": "Tweet Advanced Search",
      "description": "Advanced search for tweets",
      "method": "GET",
      "path": "/twitter/tweet/advanced_search",
      "score": 42,
      "next": {
        "tool": "get_twitterapi_endpoint",
        "arguments": { "endpoint_name": "tweet_advanced_search" }
      }
    }
  ]
}
```

### get_twitterapi_endpoint

Retrieves complete documentation for a specific API endpoint including method, path, parameters, cURL examples, and code snippets.

```json
{
  "tool": "get_twitterapi_endpoint",
  "arguments": {
    "endpoint_name": "tweet_advanced_search"
  }
}
```

Example response:
```json
{
  "endpoint_name": "tweet_advanced_search",
  "title": "Tweet Advanced Search",
  "method": "GET",
  "path": "/twitter/tweet/advanced_search",
  "full_url": "https://api.twitterapi.io/twitter/tweet/advanced_search",
  "description": "Advanced search for tweets. Each page returns up to 20 tweets.",
  "parameters": [
    { "name": "query", "required": true, "description": "Search query string" },
    { "name": "queryType", "required": false, "description": "Type of search query" },
    { "name": "cursor", "required": false, "description": "Pagination cursor" }
  ],
  "curl_example": "curl --request GET \\\n  --url 'https://api.twitterapi.io/twitter/tweet/advanced_search?query=QUERY' \\\n  --header 'X-API-Key: <api-key>'"
}
```

### list_twitterapi_endpoints

Lists all available API endpoints, optionally filtered by category. Categories include: user, tweet, community, webhook, stream, action, dm, list, trend, other.

```json
{
  "tool": "list_twitterapi_endpoints",
  "arguments": {
    "category": "user"
  }
}
```

Example response for user category:
```json
{
  "category": "user",
  "total": 11,
  "total_all": 67,
  "endpoints": [
    { "name": "get_user_by_username", "method": "GET", "path": "/twitter/user/info", "category": "user" },
    { "name": "get_user_followers", "method": "GET", "path": "/twitter/user/followers", "category": "user" },
    { "name": "get_user_followings", "method": "GET", "path": "/twitter/user/followings", "category": "user" },
    { "name": "get_user_last_tweets", "method": "GET", "path": "/twitter/user/last_tweets", "category": "user" },
    { "name": "get_user_timeline", "method": "GET", "path": "/twitter/user/tweet_timeline", "category": "user" },
    { "name": "get_user_mention", "method": "GET", "path": "/twitter/user/mentions", "category": "user" },
    { "name": "get_user_verified_followers", "method": "GET", "path": "/twitter/user/verifiedFollowers", "category": "user" },
    { "name": "get_user_about", "method": "GET", "path": "/twitter/user_about", "category": "user" },
    { "name": "batch_get_user_by_userids", "method": "GET", "path": "/twitter/user/batch_info_by_ids", "category": "user" },
    { "name": "check_follow_relationship", "method": "GET", "path": "/twitter/user/check_follow_relationship", "category": "user" },
    { "name": "search_user", "method": "GET", "path": "/twitter/user/search", "category": "user" }
  ]
}
```

### get_twitterapi_guide

Retrieves a specific guide page from the offline snapshot by page key. Available guides include pricing, qps_limits, authentication, tweet_filter_rules, changelog, and more.

```json
{
  "tool": "get_twitterapi_guide",
  "arguments": {
    "guide_name": "qps_limits"
  }
}
```

### get_twitterapi_pricing

Returns TwitterAPI.io pricing information including the credit system, endpoint costs, and QPS limits by balance level.

```json
{
  "tool": "get_twitterapi_pricing",
  "arguments": {}
}
```

Example response:
```json
{
  "credits_per_usd": 100000,
  "minimum_charge": "15 credits ($0.00015) per request",
  "costs": {
    "tweets": "15 credits per tweet",
    "profiles": "18 credits per user",
    "followers": "15 credits per follower",
    "list_calls": "150 credits per call"
  },
  "qps_limits": {
    "free": "1 request per 5 seconds",
    "paid": {
      "1000_credits": "3 QPS",
      "5000_credits": "6 QPS",
      "10000_credits": "10 QPS",
      "50000_credits": "20 QPS"
    }
  }
}
```

### get_twitterapi_auth

Returns the authentication guide with API key usage, headers, and code examples in cURL, Python, and JavaScript.

```json
{
  "tool": "get_twitterapi_auth",
  "arguments": {}
}
```

Example response:
```json
{
  "header": "x-api-key",
  "base_url": "https://api.twitterapi.io",
  "dashboard_url": "https://twitterapi.io/dashboard",
  "examples": {
    "curl": "curl -X GET \"https://api.twitterapi.io/twitter/user/info?userName=elonmusk\" \\\n  -H \"x-api-key: YOUR_API_KEY\"",
    "python": "import requests\n\nresponse = requests.get(\n    \"https://api.twitterapi.io/twitter/user/info\",\n    params={\"userName\": \"elonmusk\"},\n    headers={\"x-api-key\": \"YOUR_API_KEY\"}\n)\nprint(response.json())",
    "javascript": "const response = await fetch(\n  \"https://api.twitterapi.io/twitter/user/info?userName=elonmusk\",\n  { headers: { \"x-api-key\": \"YOUR_API_KEY\" } }\n);\nconst data = await response.json();"
  }
}
```

### get_twitterapi_url

Fetches content by URL or path from the offline snapshot. Optionally fetches live content if `fetch_live: true` is set.

```json
{
  "tool": "get_twitterapi_url",
  "arguments": {
    "url": "pricing",
    "fetch_live": false
  }
}
```

## TwitterAPI.io REST API Endpoints

### Get User By Username

Retrieves user profile information by screen name. Returns user data including ID, name, bio, follower count, and more.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/user/info?userName=elonmusk' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Tweet Advanced Search

Performs advanced search for tweets with pagination support. Each page returns up to 20 tweets. Use UNIX timestamps for time-based filtering with `since_time:` and `until_time:` operators.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/tweet/advanced_search?query=bitcoin%20lang%3Aen&queryType=Latest' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Get User Followers

Retrieves user followers in reverse chronological order. Returns 200 followers per page with cursor-based pagination.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/user/followers?userName=elonmusk&cursor=&pageSize=200' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Get User Last Tweets

Retrieves recent tweets from a user, sorted by creation time. Returns up to 20 tweets per page with cursor pagination.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/user/last_tweets?userName=elonmusk&includeReplies=false' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Get Tweets By IDs

Retrieves multiple tweets by their IDs in a single request.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/tweets?tweet_ids=1234567890,0987654321' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Get Tweet Replies

Retrieves replies to a tweet. Returns up to 20 replies per page with cursor pagination.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/tweet/replies?tweet_id=1234567890&cursor=' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Get Trends

Retrieves trending topics by WOEID (Where On Earth ID). Use 1 for worldwide, 23424977 for US.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/trends?woeid=1&count=10' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### User Login V2

Authenticates with Twitter credentials to obtain login_cookie for write operations. The login_cookie is required for all v2 write endpoints.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/user_login_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "your_email@example.com",
    "username": "your_username",
    "password": "your_password",
    "totp_secret": "your_2fa_secret"
  }'
```

### Create Tweet V2

Creates a new tweet. Requires login_cookie obtained from user_login_v2. Cost: $0.003 per call.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/create_tweet_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "text": "Hello from TwitterAPI.io!",
    "proxy": "optional_proxy_url"
  }'
```

### Like Tweet V2

Likes a tweet. Requires login_cookie. Cost: $0.002 per call.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/like_tweet_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "tweet_id": "1234567890"
  }'
```

### Retweet V2

Retweets a tweet. Requires login_cookie. Cost: $0.002 per call.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/retweet_tweet_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "tweet_id": "1234567890"
  }'
```

### Follow User V2

Follows a user. Requires login_cookie. Cost: $0.002 per call.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/follow_user_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "user_id": "44196397"
  }'
```

### Upload Media V2

Uploads media (images/videos) to Twitter for use in tweets. Requires login_cookie. Cost: $0.003 per call.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/upload_media_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "media_url": "https://example.com/image.jpg"
  }'
```

### Send DM V2

Sends a direct message to a user. Requires login_cookie. Cost: $0.003 per call. Only works with users who have DMs enabled.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/twitter/send_dm_to_user' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "user_id": "44196397",
    "text": "Hello!"
  }'
```

### Update Profile V2

Updates Twitter profile information. Requires login_cookie. Cost: $0.003 per call.

```bash
curl --request PATCH \
  --url 'https://api.twitterapi.io/twitter/update_profile_v2' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "login_cookies": "your_login_cookie",
    "name": "New Display Name",
    "bio": "Updated bio text",
    "location": "San Francisco, CA"
  }'
```

### Add Webhook Rule

Creates a tweet filter rule for webhook notifications. Rules must be activated via update_webhook_rule after creation.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/oapi/tweet_filter/add_rule' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "rule": "bitcoin OR ethereum",
    "tag": "crypto-mentions"
  }'
```

### Get Webhook Rules

Retrieves all configured tweet filter rules for webhooks and websockets.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/oapi/tweet_filter/get_rules' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Add User to Monitor Stream

Adds a user to real-time tweet monitoring. Monitors all tweets including direct tweets, quotes, replies, and retweets from the specified account.

```bash
curl --request POST \
  --url 'https://api.twitterapi.io/oapi/x_user_stream/add_user_to_monitor_tweet' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "44196397"
  }'
```

### Get Community Tweets

Retrieves tweets from a Twitter community. Returns 20 tweets per page ordered by creation time.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/community/tweets?community_id=1234567890' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Get List Timeline

Retrieves tweets from a Twitter list timeline with cursor-based pagination.

```bash
curl --request GET \
  --url 'https://api.twitterapi.io/twitter/list/tweets_timeline?list_id=1234567890&cursor=' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## JavaScript Integration Examples

### Search and Fetch Endpoint Details

Demonstrates the search-refine-fetch pattern for finding and retrieving endpoint documentation.

```javascript
async function tool(name, args) {
  const res = await callTool(name, args);
  if (res?.isError) throw new Error(res?.content?.[0]?.text ?? `Tool failed: ${name}`);
  return res?.structuredContent ?? {};
}

// Search for endpoints
const search = await tool("search_twitterapi_docs", {
  query: "advanced search",
  max_results: 10
});

// Filter to endpoint results only
const endpoints = (search.results ?? []).filter(r => r.type === "endpoint" && r.name);

// Sort by score and pick best match
endpoints.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
const best = endpoints[0];

// Fetch full endpoint documentation
const details = await tool("get_twitterapi_endpoint", {
  endpoint_name: best.name
});

console.log(details.method, details.path);
console.log(details.curl_example);
console.log(details.parameters);
```

### Pagination with Cursor

Demonstrates how to handle cursor-based pagination for endpoints that return multiple pages of results.

```javascript
async function getAllFollowers(userName, maxPages = 5) {
  const followers = [];
  let cursor = "";
  let page = 0;

  while (page < maxPages) {
    const response = await fetch(
      `https://api.twitterapi.io/twitter/user/followers?userName=${userName}&cursor=${cursor}`,
      { headers: { "x-api-key": "YOUR_API_KEY" } }
    );
    const data = await response.json();

    followers.push(...(data.users ?? []));

    // Check if more pages exist
    if (!data.next_cursor || data.next_cursor === "") {
      break;
    }

    cursor = data.next_cursor;
    page++;
  }

  return followers;
}

const followers = await getAllFollowers("elonmusk", 3);
console.log(`Fetched ${followers.length} followers`);
```

### Complete Tweet Workflow with Media

Demonstrates uploading media and creating a tweet with the v2 authenticated endpoints.

```javascript
async function postTweetWithImage(loginCookies, text, imageUrl) {
  // Step 1: Upload media
  const mediaResponse = await fetch(
    "https://api.twitterapi.io/twitter/upload_media_v2",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        login_cookies: loginCookies,
        media_url: imageUrl
      })
    }
  );
  const mediaData = await mediaResponse.json();
  const mediaId = mediaData.media_id;

  // Step 2: Create tweet with media
  const tweetResponse = await fetch(
    "https://api.twitterapi.io/twitter/create_tweet_v2",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        login_cookies: loginCookies,
        text: text,
        media_ids: [mediaId]
      })
    }
  );

  return await tweetResponse.json();
}
```

## Python Integration Examples

### Basic API Client

A simple Python client for TwitterAPI.io with error handling.

```python
import requests

class TwitterAPIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.twitterapi.io"
        self.headers = {"x-api-key": api_key}

    def get_user(self, username):
        response = requests.get(
            f"{self.base_url}/twitter/user/info",
            params={"userName": username},
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def search_tweets(self, query, max_results=20):
        response = requests.get(
            f"{self.base_url}/twitter/tweet/advanced_search",
            params={"query": query, "queryType": "Latest"},
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def get_followers(self, username, cursor=""):
        response = requests.get(
            f"{self.base_url}/twitter/user/followers",
            params={"userName": username, "cursor": cursor},
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
client = TwitterAPIClient("YOUR_API_KEY")
user = client.get_user("elonmusk")
print(f"User ID: {user['data']['id']}, Followers: {user['data']['followers_count']}")
```

### Authenticated Actions

Python example for authenticated write operations using login_cookie.

```python
import requests

def login_and_tweet(api_key, email, username, password, totp_secret, tweet_text):
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json"
    }

    # Step 1: Login to get cookies
    login_response = requests.post(
        "https://api.twitterapi.io/twitter/user_login_v2",
        headers=headers,
        json={
            "email": email,
            "username": username,
            "password": password,
            "totp_secret": totp_secret
        }
    )
    login_data = login_response.json()
    login_cookies = login_data.get("login_cookies")

    # Step 2: Create tweet
    tweet_response = requests.post(
        "https://api.twitterapi.io/twitter/create_tweet_v2",
        headers=headers,
        json={
            "login_cookies": login_cookies,
            "text": tweet_text
        }
    )

    return tweet_response.json()
```

## Summary

TwitterAPI.io MCP provides a comprehensive offline documentation server for AI assistants working with Twitter/X data. The seven MCP tools cover the full spectrum of documentation needs: `search_twitterapi_docs` for discovering endpoints and guides, `get_twitterapi_endpoint` for detailed API specifications, `list_twitterapi_endpoints` for browsing by category, `get_twitterapi_guide` and `get_twitterapi_url` for accessing guides and pages, and `get_twitterapi_pricing` and `get_twitterapi_auth` for quick access to pricing and authentication information.

The underlying TwitterAPI.io REST API supports both read operations (user profiles, tweets, followers, search, trends, communities, lists) and write operations through v2 authenticated endpoints (create tweets, like, retweet, follow, DM, profile updates). Write operations require a login_cookie obtained through the user_login_v2 endpoint and cost between $0.001-$0.003 per call. The credit-based pricing system offers 100,000 credits per USD with costs of 15-18 credits per tweet/profile fetch and QPS limits ranging from 1 request per 5 seconds (free) to 20 QPS for accounts with 50,000+ credits balance. All endpoints support cursor-based pagination for handling large result sets.