Twitter (X) MCP Agent

Overview

Build an autonomous agent that connects to Twitter/X, collects social data — mentions, keyword trends, engagement metrics — and generates analytics reports in your workspace.

This example uses @enescinar/twitter-mcp, a community-maintained MCP server — not an official Twitter/X product. Review the package source and permissions before providing your API credentials.

Prerequisites

A Twitter Developer Account with API access
API Key, API Secret, Access Token, and Access Token Secret from the Developer Portal
Node.js installed (for npx)

Environment Variables

# .env
TWITTER_API_KEY=your-api-key
TWITTER_API_SECRET=your-api-secret
TWITTER_ACCESS_TOKEN=your-access-token
TWITTER_ACCESS_TOKEN_SECRET=your-access-token-secret
ANTHROPIC_API_KEY=your-anthropic-key-here

Get these credentials from the Twitter Developer Portal. Create a project and app, then generate your API keys and access tokens under the “Keys and tokens” tab.

Installation

# With uv (recommended)
uv pip install upsonic python-dotenv

# With pip
pip install upsonic python-dotenv

Example: Brand Sentiment Report

The agent searches for mentions of a brand or keyword, performs sentiment analysis, and generates a report with CSV data.

import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task
from upsonic.tools.mcp import MCPHandler

load_dotenv()

twitter_handler = MCPHandler(
    command="npx -y @enescinar/twitter-mcp",
    env={
        "API_KEY": os.getenv("TWITTER_API_KEY"),
        "API_SECRET_KEY": os.getenv("TWITTER_API_SECRET"),
        "ACCESS_TOKEN": os.getenv("TWITTER_ACCESS_TOKEN"),
        "ACCESS_TOKEN_SECRET": os.getenv("TWITTER_ACCESS_TOKEN_SECRET")
    },
    timeout_seconds=60
)

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace="./social-reports",
    tools=[twitter_handler]
)

task = Task(
    description="""
    Search Twitter for recent tweets mentioning "upsonic" or "AI agents"
    from the last 7 days. Collect at least 50 tweets.

    For each tweet, classify the sentiment as: positive, neutral, or negative.

    Write the following files:
    - 'tweets.csv' with columns: date, author, text, likes, retweets,
      replies, sentiment
    - 'sentiment_report.md' with:
      * Total tweets analyzed
      * Sentiment distribution (table with counts and percentages)
      * Top 5 most engaging tweets (highest likes + retweets)
      * Common themes in positive mentions
      * Common complaints in negative mentions
      * Key influencers (authors with highest follower counts)
      * Recommendations for engagement strategy
    """
)

agent.print_do(task)

Example: Competitor Monitoring Dashboard

The agent tracks multiple competitors and creates a comparative analysis report.

import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task
from upsonic.tools.mcp import MCPHandler

load_dotenv()

twitter_handler = MCPHandler(
    command="npx -y @enescinar/twitter-mcp",
    env={
        "API_KEY": os.getenv("TWITTER_API_KEY"),
        "API_SECRET_KEY": os.getenv("TWITTER_API_SECRET"),
        "ACCESS_TOKEN": os.getenv("TWITTER_ACCESS_TOKEN"),
        "ACCESS_TOKEN_SECRET": os.getenv("TWITTER_ACCESS_TOKEN_SECRET")
    },
    timeout_seconds=60
)

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace="./social-reports",
    tools=[twitter_handler]
)

task = Task(
    description="""
    Monitor Twitter activity for three AI agent frameworks:
    "langchain", "crewai", and "upsonic".

    For each framework, search recent tweets and collect:
    - Tweet volume (number of mentions)
    - Average engagement (likes + retweets per tweet)
    - Overall sentiment

    Write the following files:
    - 'competitor_data.csv' with columns: framework, date, tweet_count,
      avg_likes, avg_retweets, positive_pct, negative_pct
    - 'competitor_report.md' with:
      * Comparison table (volume, engagement, sentiment per framework)
      * Share of voice analysis (% of total mentions)
      * Notable tweets for each framework
      * Trending topics per framework
      * Competitive positioning insights
    """
)

agent.print_do(task)

Available Tools

Twitter MCP servers typically expose tools including:

Tool	Description
`search_tweets`	Search for tweets by keyword or query
`post_tweet`	Post a new tweet
`get_user_tweets`	Get recent tweets from a user
`get_mentions`	Get mentions of the authenticated user
`reply_to_tweet`	Reply to a specific tweet
`get_tweet`	Get details of a specific tweet

Security Notes

Use a dedicated Twitter app with read-only permissions for analytics agents.
Store all API keys and tokens in .env — never hardcode them.
Twitter API has rate limits — set appropriate tool_call_limit to avoid hitting them.
Only grant write permissions if the agent needs to post or reply.

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Twitter (X) MCP Agent

Overview

Prerequisites

Environment Variables

Installation

Example: Brand Sentiment Report

Example: Competitor Monitoring Dashboard

Available Tools

Security Notes

​Overview

​Prerequisites

​Environment Variables

​Installation

​Example: Brand Sentiment Report

​Example: Competitor Monitoring Dashboard

​Available Tools

​Security Notes

Overview

Prerequisites

Environment Variables

Installation

Example: Brand Sentiment Report

Example: Competitor Monitoring Dashboard

Available Tools

Security Notes