playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Twitter MCP server

Provides a TypeScript-based server for interacting with Twitter, enabling tweet operations, user profile management, and Grok AI integration through multiple authentication methods.
Back to servers
Setup instructions
Provider
Ryan Mac
Release date
Mar 08, 2025
Language
TypeScript
Package
npm
Stats
505 downloads
14 stars
View on GitHub

The Twitter MCP server provides a bridge for AI models to interact with Twitter without direct API access. It supports multiple authentication methods and offers various Twitter operations including tweet management, user interactions, and integration with Grok.

Installation

Global Installation

npm install -g agent-twitter-client-mcp

Local Installation

npm install agent-twitter-client-mcp

Running the Server

Start the MCP server after installation:

# If installed globally
agent-twitter-client-mcp

# If installed locally
npx agent-twitter-client-mcp

Port Configuration

By default, the server runs on port 3000. You can change this:

Using environment variables:

PORT=3001 npx agent-twitter-client-mcp

Using Docker Compose: Add to your .env file:

MCP_HOST_PORT=3001    # The port on your host machine
MCP_CONTAINER_PORT=3000  # The port inside the container

Then run:

docker-compose up -d

Authentication Configuration

Cookie Authentication (Recommended)

{
  "AUTH_METHOD": "cookies",
  "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
}

To obtain cookies:

  1. Log in to Twitter in your browser
  2. Open Developer Tools (F12)
  3. Go to the Application tab > Cookies
  4. Copy the values of auth_token, ct0, and twid cookies
  5. Include the Domain=.twitter.com part for each cookie

Username/Password Authentication

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "[email protected]", 
  "TWITTER_2FA_SECRET": "your_2fa_secret"
}

Note: Email and 2FA secret are optional, but 2FA secret is required if 2FA is enabled.

Twitter API Authentication

{
  "AUTH_METHOD": "api",
  "TWITTER_API_KEY": "your_api_key",
  "TWITTER_API_SECRET_KEY": "your_api_secret_key",
  "TWITTER_ACCESS_TOKEN": "your_access_token",
  "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}

Integration with Claude Desktop

  1. Configure Claude Desktop by editing your config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "agent-twitter-client-mcp": {
      "command": "npx",
      "args": ["-y", "agent-twitter-client-mcp"],
      "env": {
        "AUTH_METHOD": "cookies",
        "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
      }
    }
  }
}
  1. Restart Claude Desktop

Available Tools

The MCP server provides several tools:

  • get_user_tweets: Fetch tweets from a specific user
  • get_tweet_by_id: Fetch a specific tweet by ID
  • search_tweets: Search for tweets
  • send_tweet: Post a new tweet
  • send_tweet_with_poll: Post a tweet with a poll
  • like_tweet: Like a tweet
  • retweet: Retweet a tweet
  • quote_tweet: Quote a tweet
  • get_user_profile: Get a user's profile
  • follow_user: Follow a user
  • get_followers: Get a user's followers
  • get_following: Get users a user is following
  • grok_chat: Chat with Grok via Twitter
  • health_check: Check the health of the server

Testing Interface

The MCP includes an interactive command-line interface for testing:

npx agent-twitter-client-mcp-test
# or if installed locally
npm run test:interface

This launches a REPL where you can test various functions:

agent-twitter-client-mcp> help

Available commands:
  health                     Run a health check
  profile <username>         Get a user profile
  tweets <username> [count]  Get tweets from a user
  tweet <id>                 Get a specific tweet by ID
  search <query> [count]     Search for tweets
  post <text>                Post a new tweet
  like <id>                  Like a tweet
  retweet <id>               Retweet a tweet
  quote <id> <text>          Quote a tweet
  follow <username>          Follow a user
  followers <userId> [count] Get a user's followers
  following <userId> [count] Get users a user is following
  grok <message>             Chat with Grok
  help                       Show available commands
  exit                       Exit the test interface

Example Test Commands

# Run a health check
agent-twitter-client-mcp> health

# Search for tweets
agent-twitter-client-mcp> search mcp 2

# Get a user's profile
agent-twitter-client-mcp> profile elonmusk

# Get tweets from a user
agent-twitter-client-mcp> tweets openai 5

# Chat with Grok
agent-twitter-client-mcp> grok Explain quantum computing in simple terms

Advanced Usage

Working with Media

To post a tweet with an image:

I want to post a tweet with an image. The tweet should say "Beautiful sunset today!" and include this image.

To post a tweet with a video:

I want to post a tweet with a video. The tweet should say "Check out this amazing video!" and include the video file.

Creating Polls

To create a poll:

Create a Twitter poll asking "What's your favorite programming language?" with options: Python, JavaScript, Rust, and Go. The poll should run for 24 hours.

Grok Integration

Grok integration requires agent-twitter-client v0.0.19 or higher.

Using Grok

To have a conversation with Grok:

Use Grok to explain quantum computing to me. Ask it to include some real-world applications.

To continue a conversation:

Continue the Grok conversation and ask it to elaborate on quantum entanglement.

Grok Capabilities

Grok on Twitter can provide:

  • Current trending topics on Twitter
  • Analysis of recent tweets on specific subjects
  • Information about Twitter users and their content
  • Real-time events being discussed on the platform

Example queries:

  • "What are the trending topics on Twitter right now?"
  • "Analyze the sentiment around AI on Twitter"
  • "What are people saying about the latest Apple event?"

Grok Rate Limits

  • Non-premium accounts: 25 messages per 2 hours
  • Premium accounts: Higher limits

Troubleshooting

Authentication Issues

Cookie Authentication Problems

  • Check cookie expiration
  • Verify cookie format
  • Ensure you've included the essential cookies

Credential Authentication Problems

  • Provide 2FA secret if required
  • Be aware of account lockouts
  • Consider captcha challenges

API Authentication Problems

  • Verify API key permissions
  • Watch for rate limiting
  • Check for API changes

Operation Errors

Tweet Posting Failures

  • Check content restrictions
  • Verify media format
  • Be aware of rate limiting

Grok Issues

  • Ensure you have v0.0.19+ of agent-twitter-client
  • Verify cookie format and validity
  • Be aware of rate limits
  • Check environment file location

Server Diagnostics

Use the health_check tool to diagnose server issues:

Run a health check on the agent-twitter-client-mcp server to diagnose any issues.

The health check reports on:

  • Authentication status
  • API connectivity
  • Memory usage

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "agent-twitter-client-mcp" '{"command":"npx","args":["-y","agent-twitter-client-mcp"],"env":{"AUTH_METHOD":"cookies","TWITTER_COOKIES":"[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "agent-twitter-client-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "agent-twitter-client-mcp"
            ],
            "env": {
                "AUTH_METHOD": "cookies",
                "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "agent-twitter-client-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "agent-twitter-client-mcp"
            ],
            "env": {
                "AUTH_METHOD": "cookies",
                "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later