claude mcp add twitter \
  -e TWITTER_TOKEN=$TWITTER_TOKEN \
  -- uv --directory /path/to/twitter-mcp run twitter-mcp

{
  "mcpServers": {
    "twitter": {
      "command": "uv",
      "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
      "env": {
        "TWITTER_TOKEN": "${TWITTER_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "twitter": {
      "command": "uv",
      "args": ["--directory", "/path/to/twitter-mcp", "run", "twitter-mcp"],
      "env": {
        "TWITTER_TOKEN": "${TWITTER_TOKEN}"
      }
    }
  }
}

mcpServers:
  - name: twitter
    command: uv
    args:
      - --directory
      - /path/to/twitter-mcp
      - run
      - twitter-mcp
    env:
      TWITTER_TOKEN: ${TWITTER_TOKEN}

{
  "api_base_url": "https://ai.6551.io",
  "api_token": "your-token-here",
  "max_rows": 100
}

# Example use from AI assistant:
# "Show me @elonmusk's profile"
{
  "username": "elonmusk"
}

{
  "user_id": "44196397"
}

# "What did @VitalikButerin tweet recently"
{
  "username": "VitalikButerin",
  "count": 20
}

{
  "tweet_id": "1234567890"
}

{
  "article_id": "1234567890"
}

# "Search Bitcoin related tweets"
{
  "query": "Bitcoin",
  "count": 50
}

# "Popular tweets about ETH with 1000+ likes"
{
  "query": "ETH",
  "min_likes": 1000,
  "min_retweets": 100,
  "language": "en",
  "count": 30
}

# "Who quoted this tweet"
{
  "tweet_id": "1234567890",
  "count": 50
}

# "Who retweeted this tweet"
{
  "tweet_id": "1234567890",
  "count": 100
}

# "Show my Twitter watch list"
{}

# "Monitor @elonmusk with follower tracking"
{
  "username": "elonmusk",
  "event_types": ["NEW_FOLLOWER", "NEW_UNFOLLOWER", "NEW_TWEET"],
  "remark": "Tesla CEO",
  "ca": "0x1234..."  # Optional contract address
}

{
  "username": "elonmusk"
}

# "Who followed @elonmusk recently"
{
  "username": "elonmusk",
  "event_type": "NEW_FOLLOWER",
  "count": 50
}

# "What tweets did @elonmusk delete"
{
  "username": "elonmusk",
  "count": 20
}

# "Which KOLs follow @elonmusk"
{
  "username": "elonmusk",
  "count": 100
}

{
  "userId": "44196397",
  "screenName": "elonmusk",
  "name": "Elon Musk",
  "description": "Bio text...",
  "followersCount": 170000000,
  "friendsCount": 500,
  "statusesCount": 30000,
  "verified": true,
  "profileImageUrl": "https://...",
  "profileBannerUrl": "https://...",
  "createdAt": "2009-06-02T20:12:29Z"
}

{
  "id": "1234567890",
  "text": "Tweet content...",
  "createdAt": "2024-02-20T12:00:00Z",
  "language": "en",
  "retweetCount": 100,
  "favoriteCount": 500,
  "replyCount": 20,
  "quoteCount": 10,
  "viewCount": 10000,
  "userScreenName": "elonmusk",
  "userName": "Elon Musk",
  "userIdStr": "44196397",
  "userFollowers": 170000000,
  "userVerified": true,
  "conversationId": "1234567890",
  "isReply": false,
  "isQuote": false,
  "hashtags": ["crypto", "bitcoin"],
  "media": [
    {
      "type": "photo",
      "url": "https://...",
      "thumbUrl": "https://..."
    }
  ],
  "urls": [
    {
      "url": "https://t.co/...",
      "expandedUrl": "https://example.com",
      "displayUrl": "example.com"
    }
  ],
  "mentions": [
    {
      "username": "VitalikButerin",
      "name": "Vitalik Buterin"
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "twitter.subscribe"
}

{
  "jsonrpc": "2.0",
  "method": "twitter.event",
  "params": {
    "id": 123456,
    "twAccount": "elonmusk",
    "twUserName": "Elon Musk",
    "profileUrl": "https://twitter.com/elonmusk",
    "eventType": "NEW_TWEET",
    "content": { /* tweet object */ },
    "ca": "0x1234...",
    "remark": "Custom note",
    "createdAt": "2026-03-06T10:00:00Z"
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "twitter.unsubscribe"
}

# High-engagement tweets in specific timeframe
search_twitter_advanced(
    query="AI",
    min_likes=1000,
    min_retweets=500,
    since="2024-01-01",
    until="2024-12-31",
    verified_only=True,
    language="en"
)

# Add multiple KOLs to watch list
for username in ["elonmusk", "VitalikButerin", "naval"]:
    add_twitter_watch(
        username=username,
        event_types=["NEW_TWEET", "NEW_FOLLOWER"],
        remark=f"Tracking {username}"
    )

# Get full engagement picture for a tweet
tweet = get_twitter_tweet_by_id(tweet_id="1234567890")
quotes = get_twitter_quote_tweets_by_id(tweet_id="1234567890")
retweet_users = get_twitter_retweet_users_by_id(tweet_id="1234567890")

# Compare followers vs KOL followers
all_followers = get_twitter_follower_events(
    username="elonmusk",
    event_type="NEW_FOLLOWER"
)
kol_followers = get_twitter_kol_followers(username="elonmusk")

cd /path/to/twitter-mcp
uv sync
export TWITTER_TOKEN=your-token
uv run twitter-mcp

npx @modelcontextprotocol/inspector \
  uv --directory /path/to/twitter-mcp run twitter-mcp

src/twitter_mcp/
├── server.py      # Entry point
├── app.py         # FastMCP instance
├── config.py      # Config loader
├── api_client.py  # HTTP client
└── tools.py       # Tool implementations