TweetMCP

# Twitter MCP Server with HuggingFace Integration A comprehensive Model Context Protocol (MCP) server that provides full Twitter API functionality with HuggingFace AI integration for enhanced social media automation and content creation. ## � Features ### Basic Reading - **Fetch Individual Tweets**: Get detailed tweet information by ID - **User Timelines**: Retrieve latest tweets from any user - **Search Tweets**: Search public tweets by keyword/hashtag with filtering - **User Profiles**: Pull complete profile data for any username ### Posting & Replying - **Create Tweets**: Post text-only or text + media tweets - **Reply to Tweets**: Create threaded replies to existing tweets - **Multi-Tweet Threads**: Publish complete threads in one operation ### User Interactions - **Like/Unlike**: Engage with tweets through likes - **Retweet/Unretweet**: Share and unshare content - **Quote Tweets**: Quote tweet with custom commentary ### Media Handling - **Upload Media**: Support for images (JPEG, PNG, GIF) and videos (MP4) - **Alt-Text Support**: Add accessibility descriptions to uploaded media - **URL Media Upload**: Upload media directly from URLs ### Timelines & Trends - **Home Timeline**: Access authenticated user's feed - **List Timelines**: Get tweets from specific Twitter Lists - **Trending Topics**: Retrieve trending hashtags and topics by location ### Relationships & Account Management - **Follow/Unfollow**: Manage following relationships - **Followers/Following Lists**: Get user relationship data - **Account Profile**: Access authenticated user's profile details ### Lists and Collections - **Create/Update Lists**: Manage Twitter Lists - **List Membership**: Add and remove users from lists - **List Management**: Full CRUD operations for lists ### Search Utilities - **User ID Lookup**: Convert usernames to user IDs - **Advanced Search**: Complex queries with date ranges and filters ### Administrative Tools - **Delete Tweets**: Remove your own tweets - **Rate Limit Monitoring**: Check API usage and limits - **Bulk Operations**: Perform actions on multiple tweets safely ### HuggingFace AI Integration - **Text Generation**: Generate tweet content using HF models - **Sentiment Analysis**: Analyze tweet sentiment with AI - **Text Enhancement**: Improve grammar, style, and engagement - **Translation**: Translate tweets to multiple languages ## 🛠️ Setup ### Prerequisites - Python 3.8+ - Twitter Developer Account with API v2 access - HuggingFace account (optional, for AI features) ### Installation 1. **Clone the repository**: ```bash git clone <repository-url> cd hf-pr-mcp ``` 2. **Install dependencies**: ```bash pip install -r requirements.txt ``` 3. **Configure environment variables**: ```bash cp env.example .env ``` 4. **Get Twitter API credentials**: - Visit [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard) - Create a new app and generate API keys - Add credentials to `.env` file 5. **Get HuggingFace token** (optional): - Visit [HuggingFace Settings](https://huggingface.co/settings/tokens) - Generate a new token - Add to `.env` file ### Environment Variables ```env # Twitter API Credentials (required) TWITTER_API_KEY=your_twitter_api_key_here TWITTER_API_SECRET=your_twitter_api_secret_here TWITTER_ACCESS_TOKEN=your_twitter_access_token_here TWITTER_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret_here TWITTER_BEARER_TOKEN=your_twitter_bearer_token_here # HuggingFace API Token (optional) HF_TOKEN=your_huggingface_token_here ``` ## 🚀 Usage ### Start the MCP Server ```bash python mcp_server.py ``` ### Example Tool Calls #### Basic Reading ```python # Fetch a tweet by ID fetch_tweet_by_id("1234567890") # Get user timeline get_user_timeline("elonmusk", max_results=10) # Search tweets search_tweets("#AI #MachineLearning", result_type="recent", max_results=20) ``` #### Posting Content ```python # Create a simple tweet create_tweet("Hello, Twitter! 🐦") # Reply to a tweet reply_to_tweet("1234567890", "Great point!") # Create a thread create_thread([ "Thread about AI advancements (1/3)", "First, let's talk about transformers...", "In conclusion, the future is bright! 🚀" ]) ``` #### User Interactions ```python # Like a tweet like_tweet("1234567890") # Retweet content retweet("1234567890") # Quote tweet quote_tweet("1234567890", "This is exactly what I was thinking!") ``` #### Media Upload ```python # Upload image with alt text upload_media(base64_image_data, "image/jpeg", alt_text="Beautiful sunset") # Upload from URL upload_media_from_url("https://example.com/image.jpg", alt_text="Example image") ``` #### HuggingFace Integration ```python # Generate tweet content generate_tweet_with_hf("Write a tweet about artificial intelligence") # Analyze sentiment analyze_tweet_sentiment_hf("I love this new AI technology!") # Enhance text enhance_tweet_with_hf("this is grate", enhancement_type="grammar") # Translate tweet translate_tweet_hf("Hello world!", target_language="es") ``` ## 📊 Response Format All tools return responses in a consistent JSON format: ```json { "content": [ { "type": "text", "text": "Response content here" } ] } ``` ## ⚡ Rate Limiting The server includes automatic rate limiting to respect Twitter's API limits: - Automatic retry with exponential backoff - Rate limit status monitoring - Bulk operation safety limits - Smart delays between operations ## 🔧 Advanced Features ### Bulk Operations Process multiple tweets safely: ```python bulk_process_tweets("like", ["tweet1", "tweet2", "tweet3"], max_per_request=10) ``` ### Server Status Monitor server health and configuration: ```python get_server_status() ``` ### Rate Limit Monitoring Check current API usage: ```python get_rate_limits() ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## 📄 License MIT License - see LICENSE file for details ## 🆘 Support - Create an issue for bugs or feature requests - Check Twitter API documentation for credential setup - Review HuggingFace documentation for AI model usage ## 🔗 Related Links - [Twitter API v2 Documentation](https://developer.twitter.com/en/docs/api) - [HuggingFace Models](https://huggingface.co/models) - [Model Context Protocol](https://github.com/anthropics/mcp) - [FastMCP Framework](https://github.com/jlowin/fastmcp)