agent-twitter-client-mcp

A Model Context Protocol (MCP) server that integrates with Twitter using the agent-twitter-client package, allowing AI models to interact with Twitter without direct API access.

Features

• Authentication Options:

  • Cookie-based authentication (recommended)
  • Username/password authentication
  • Twitter API v2 credentials

• Tweet Operations:

  • Fetch tweets from users
  • Get specific tweets by ID
  • Search tweets
  • Send tweets with text and media
  • Create polls
  • Like, retweet, and quote tweets

• User Operations:

  • Get user profiles
  • Follow users
  • Get followers and following lists

• Grok Integration:

  • Chat with Grok via Twitter's interface
  • Continue conversations with conversation IDs
  • Get web search results and citations
  • Access Twitter's real-time data through Grok
  • Note: Grok functionality requires agent-twitter-client v0.0.19 or higher

Documentation

• Developer Guide - Comprehensive guide for developers
• Testing Guide - Instructions for testing the MCP
• Agent Guide - Guide for AI agents on how to use the Twitter MCP
• Contributing Guide - Guidelines for contributing to this project
• Changelog - History of changes to this project
• Demo README - Guide for running the demo scripts
• Grok Examples - Documentation for the Grok AI integration examples

Quick Start

Installation

# Install globally
npm install -g agent-twitter-client-mcp

# Or install locally
npm install agent-twitter-client-mcp

Basic Usage

1. Create a .env file with your Twitter credentials (see Authentication Methods)
2. Run the MCP server:

# If installed globally
agent-twitter-client-mcp

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

Demo Scripts

The package includes a demo directory with example scripts that demonstrate various features:

# Clone the repository to access the demo scripts
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp/demo

# Run the interactive demo menu
./run-demo.sh

# Run a specific demo script
./run-demo.sh --script tweet-search.js

# Run Grok AI examples (requires agent-twitter-client v0.0.19)
./run-demo.sh --script simple-grok.js --use-local-agent-twitter-client
./run-demo.sh --script grok-chat.js --use-local-agent-twitter-client

See the Demo README for more details.

Port Configuration

By default, the MCP server runs on port 3000. If you need to change this (for example, if you already have an application running on port 3000), you have several options:

Option 1: Using Environment Variables

Set the PORT environment variable:

PORT=3001 npx agent-twitter-client-mcp

Option 2: Using Docker Compose

If using Docker Compose, you can configure both the host and container ports in your .env file:

# .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

This will map port 3001 on your host to port 3000 in the container, allowing you to access the MCP at http://localhost:3001 while your other application continues to use port 3000.

Setup with Claude Desktop

1. Configure Claude Desktop to use this MCP by adding to 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

Authentication Methods

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. Make sure to 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": "your_email@example.com", // Optional
  "TWITTER_2FA_SECRET": "your_2fa_secret" // Optional, 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"
}

Available 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 Twitter MCP 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 MCP 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

Example Usage

Ask Claude to:

• "Search Twitter for tweets about AI"
• "Post a tweet saying 'Hello from Claude!'"
• "Get the latest tweets from @OpenAI"
• "Chat with Grok about quantum computing"

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.

Interacting with 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 with Grok:

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

Grok's Unique Capabilities

Grok on Twitter has access to real-time Twitter data that even the standalone Grok API doesn't have. This means you can ask Grok about:

• 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?"
• "Show me information about popular memecoins being discussed today"

Grok Authentication Requirements

Grok functionality requires proper authentication. The MCP supports two methods:

1. Cookie Authentication (Recommended):

   • Cookies must be in JSON array format
   • Example: 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"]
   • Essential cookies are auth_token, ct0, and twid

2. Username/Password Authentication:

   • Set TWITTER_USERNAME and TWITTER_PASSWORD in your environment
   • May encounter Cloudflare protection in some cases

Grok Rate Limits

Grok has rate limits that may affect usage:

• Non-premium accounts: 2

---