RanL703/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:

   git clone <repository-url>
   cd hf-pr-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   cp env.example .env
   

4. Get Twitter API credentials:

   • Visit Twitter Developer Portal
   • Create a new app and generate API keys
   • Add credentials to .env file

5. Get HuggingFace token (optional):

   • Visit HuggingFace Settings
   • Generate a new token
   • Add to .env file

Environment Variables

# 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

python mcp_server.py

Example Tool Calls

Basic Reading

# 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

# 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

# Like a tweet
like_tweet("1234567890")

# Retweet content
retweet("1234567890")

# Quote tweet
quote_tweet("1234567890", "This is exactly what I was thinking!")

Media Upload

# 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

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

{
  "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:

bulk_process_tweets("like", ["tweet1", "tweet2", "tweet3"], max_per_request=10)

Server Status

Monitor server health and configuration:

get_server_status()

Rate Limit Monitoring

Check current API usage:

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
• HuggingFace Models
• Model Context Protocol
• FastMCP Framework