agent-twitter-client-mcp

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](https://github.com/elizaOS/agent-twitter-client/releases/tag/0.0.19) or higher

Documentation

• [Developer Guide](docs/DEVELOPER_GUIDE.md) - Comprehensive guide for developers

• [Testing Guide](docs/TESTING.md) - Instructions for testing the MCP

• [Agent Guide](docs/AGENT_GUIDE.md) - Guide for AI agents on how to use the Twitter MCP

• [Contributing Guide](CONTRIBUTING.md) - Guidelines for contributing to this project

• [Changelog](CHANGELOG.md) - History of changes to this project

• [Demo README](demo/README.md) - Guide for running the demo scripts

• [Grok Examples](demo/GROK_EXAMPLES.md) - Documentation for the Grok AI integration examples

Quick Start

Installation

Basic Usage

1. Create a `.env` file with your Twitter credentials (see [Authentication Methods](#authentication-methods))

2. Run the MCP server:

Demo Scripts

Port Configuration

Option 1: Using Environment Variables

Option 2: Using Docker Compose

Setup with Claude Desktop

1. Configure Claude Desktop to use this MCP by adding to your config file:

1. Restart Claude Desktop

Authentication Methods

Cookie Authentication (Recommended)

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

Twitter API Authentication

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

Example Test Commands

Example Usage

• "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

Creating Polls

Interacting with Grok

Grok's Unique Capabilities

• 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

• "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

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

• Non-premium accounts: 25 messages per 2 hours

• Premium accounts: Higher limits

Troubleshooting

Authentication Issues

Cookie Authentication Problems

1. **Cookie Expiration**: Twitter cookies typically expire after a certain period. Try refreshing your cookies by logging out and back into Twitter.

2. **Cookie Format**: Ensure your cookies are properly formatted as a JSON array of strings with the correct domain.

3. **Required Cookies**: Make sure you've included the essential cookies: `auth_token`, `ct0`, and `twid`.

Credential Authentication Problems

1. **Two-Factor Authentication**: If your account has 2FA enabled, you'll need to provide the `TWITTER_2FA_SECRET`.

2. **Account Lockouts**: Too many failed login attempts may lock your account. Check your email for account verification requests.

3. **Captcha Challenges**: Twitter may present captcha challenges that the client can't handle automatically.

API Authentication Problems

1. **API Key Permissions**: Ensure your API keys have the necessary permissions for the actions you're trying to perform.

2. **Rate Limiting**: Twitter API has rate limits that may cause failures if exceeded.

3. **API Changes**: Twitter occasionally changes its API, which may cause compatibility issues.

Operation Errors

Tweet Posting Failures

1. **Content Restrictions**: Twitter may block tweets that violate its content policies.

2. **Media Format Issues**: Ensure media is properly formatted and encoded.

3. **Rate Limiting**: Twitter limits how frequently you can post.

Search Problems

1. **Query Syntax**: Ensure your search query follows Twitter's search syntax.

2. **Search Limitations**: Some search modes may have restrictions or require specific permissions.

Grok Issues

1. **Version Requirement**: - Grok requires [agent-twitter-client v0.0.19](https://github.com/elizaOS/agent-twitter-client/releases/tag/0.0.19) or higher - The current package uses v0.0.18 for basic functionality - For the demo scripts, use the `--use-local-agent-twitter-client` flag to temporarily install v0.0.19

2. **Authentication Issues**: - Cookie Format: Ensure cookies are in the correct JSON array format - Cookie Validity: Twitter cookies expire after a certain period - Cloudflare Protection: Username/password authentication may be blocked by Cloudflare - Premium Requirement: Grok access requires a Twitter Premium subscription

3. **Rate Limits**: - Non-premium accounts: 25 messages per 2 hours - Error Message: "Rate Limited: You've reached the limit..." - Solution: Wait until the rate limit resets or upgrade to a premium account

4. **Environment File Location**: - For the demo scripts, make sure your credentials are in `demo/.env`, not in the root `.env` file - Use the `--debug-env` flag to check which environment variables are being loaded

Server Issues

Health Check

• Authentication status

• API connectivity

• Memory usage

Logging

• `error.log`: Contains error-level messages

• `combined.log`: Contains all log messages

Development

Prerequisites

• Node.js 18+

• npm

Setup

1. Clone the repository

1. Install dependencies

1. Create a `.env` file with configuration:

1. Build the project

1. Start the server

Environment Variables

• `LOG_LEVEL`: Set logging level (error, warn, info, debug)

• `NODE_ENV`: Set environment (development, production)

Docker

Using Docker Directly

Using Docker Compose

1. Create a `.env` file with your Twitter credentials

2. Run with docker-compose:

Environment Variables in Docker

1. **In the docker-compose.yml file** (already configured)

2. **Through a .env file** (recommended for docker-compose)

3. **Directly in the docker run command** (as shown above)

Persisting Logs

Security Considerations

• **Credential Storage**: Store credentials securely, preferably using environment variables or a secure vault.

• **Rate Limiting**: Implement rate limiting to prevent abuse of the Twitter API.

• **Content Validation**: Validate all content before posting to prevent malicious use.

License