Engagio MCP

Twitter engagement intelligence for Claude Code. Find high-value tweets, post strategic replies, track performance.

What It Does

• Monitor accounts - Track tweets from people you want to engage with
• Monitor topics - Track hashtags and keywords (#buildinpublic, AI agents)
• Score opportunities - Rank tweets by engagement velocity + author reach
• Post replies - Reply directly from Claude with queue spacing
• Track analytics - See which accounts give you the best engagement ROI
• Timing insights - Learn when your replies perform best

Setup

1. Install dependencies

cd engagio-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure environment

Create .env file:

# Twitter API (Official - for posting)
TWITTER_API_KEY=your_api_key
TWITTER_API_KEY_SECRET=your_api_key_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret

# twitterapi.io (for reading - cheaper)
TWITTERAPI_IO_TOKEN=your_twitterapi_io_token

# Supabase
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_anon_key

3. Set up database

Create these tables in Supabase:

-- Core tables
CREATE TABLE monitored_accounts (
    username TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    name TEXT,
    followers INT DEFAULT 0,
    bio TEXT,
    notes TEXT,
    last_fetched TIMESTAMP WITH TIME ZONE,
    added_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    -- ROI tracking
    total_replies INT DEFAULT 0,
    total_likes_received INT DEFAULT 0,
    avg_engagement FLOAT DEFAULT 0
);

CREATE TABLE tweets (
    id TEXT PRIMARY KEY,
    author_username TEXT NOT NULL,
    author_user_id TEXT,
    text TEXT NOT NULL,
    likes INT DEFAULT 0,
    retweets INT DEFAULT 0,
    replies INT DEFAULT 0,
    views INT DEFAULT 0,
    posted_at TIMESTAMP WITH TIME ZONE,
    fetched_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    engagement_score FLOAT DEFAULT 0,
    -- Enhanced fields
    is_retweet BOOLEAN DEFAULT FALSE,
    is_thread BOOLEAN DEFAULT FALSE,
    thread_id TEXT,
    author_followers INT DEFAULT 0
);

CREATE TABLE replies (
    id SERIAL PRIMARY KEY,
    original_tweet_id TEXT NOT NULL REFERENCES tweets(id),
    original_author TEXT NOT NULL,
    reply_text TEXT NOT NULL,
    reply_tweet_id TEXT,
    replied_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    likes_received INT DEFAULT 0,
    replies_received INT DEFAULT 0,
    reply_tone TEXT,
    -- Timing analytics
    hour_of_day INT,
    day_of_week INT
);

-- Topic monitoring
CREATE TABLE monitored_topics (
    id SERIAL PRIMARY KEY,
    topic TEXT NOT NULL UNIQUE,
    type TEXT DEFAULT 'hashtag',
    added_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Reply queue
CREATE TABLE reply_queue (
    id SERIAL PRIMARY KEY,
    tweet_id TEXT NOT NULL,
    reply_text TEXT NOT NULL,
    scheduled_for TIMESTAMP WITH TIME ZONE,
    status TEXT DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    posted_at TIMESTAMP WITH TIME ZONE
);

4. Add to Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "engagio": {
      "type": "stdio",
      "command": "/path/to/engagio-mcp/venv/bin/python",
      "args": ["/path/to/engagio-mcp/server.py"],
      "env": {}
    }
  }
}

Restart Claude Code.

Usage

Monitor accounts

"Add @levelsio to my monitored accounts"
"Add these accounts: sama, paulg, naval"
"List my monitored accounts"
"Remove @someone from monitoring"
"Backfill bios for all accounts"
"Add notes for @levelsio: Built Nomad List, Photo AI"

Monitor topics

"Add topic #buildinpublic"
"Add topic AI agents"
"List my monitored topics"
"Fetch tweets for #buildinpublic"

Find opportunities (cost-optimized)

"Fetch tweets from top 10 accounts" → fetch_tweets(top_n=10) - CHEAP
"Fetch from levelsio only" → fetch_tweets(username="levelsio") - CHEAPEST
"Fetch all tweets" → fetch_tweets() - EXPENSIVE (all accounts)
"Show me top 5 engagement opportunities" → FREE (uses cache)
"Show opportunities with min 100k followers" → FREE
"Search cached tweets about AI" → search_tweets("AI", cache_only=True) - FREE
"Search Twitter for AI agents" → search_tweets("AI agents") - costs money

Engage

"Generate 3 reply options for that tweet"
"Post this reply: [your text]"
"Queue this reply: [your text]"
"View my reply queue"
"Post next queued reply"

Track performance

"Update my reply performance stats"
"Show my engagement analytics"
"Show my reply history"
"Show account ROI"
"Show timing insights"

Thread context

"Get thread for tweet [id]"

Scoring Algorithm

Tweets are scored by engagement velocity weighted by author reach:

base_score = (likes + retweets×2 + replies×3) / √(minutes_old + 1)
follower_multiplier = 1 + log10(followers) / 10
score = base_score × follower_multiplier

• Higher engagement = higher score
• Newer tweets = higher score
• Replies weighted highest (conversation value)
• More followers = higher multiplier (log scale to prevent domination)

Architecture

Claude Code
    ↓
Engagio MCP
    ├── twitterapi.io (READ - $0.15/1000 tweets)
    ├── Twitter API (WRITE - free tier, 17/day)
    └── Supabase (persistent storage)

Tools Reference

Account Management

Tool	Description
engagio_add_account(username)	Monitor a Twitter account (auto-fetches bio)
engagio_add_accounts_bulk(usernames)	Add multiple accounts with rate limit handling
engagio_remove_account(username)	Stop monitoring
engagio_remove_accounts_bulk(usernames)	Remove multiple accounts
engagio_list_accounts()	List monitored accounts with bios/notes
engagio_backfill_bios()	Fetch bios for accounts missing them
engagio_update_account_notes(username, notes)	Add accomplishments/context

Topic Management

Tool	Description
engagio_add_topic(topic)	Monitor a hashtag or keyword
engagio_remove_topic(topic)	Stop monitoring topic
engagio_list_topics()	List monitored topics
engagio_fetch_topic_tweets(topic?, hours?)	Fetch tweets for topics

Tweet Discovery (Cost-Optimized)

Tool	Description	Cost
engagio_fetch_tweets(top_n=10)	Fetch from top N accounts by followers	~$0.015
engagio_fetch_tweets(username="x")	Fetch from single account	~$0.0015
engagio_fetch_tweets()	Fetch from ALL accounts	~$0.09
engagio_get_opportunities(...)	Ranked opportunities with filters	FREE
engagio_search_tweets(query, cache_only=True)	Search cached tweets	FREE
engagio_search_tweets(query)	Search Twitter API	costs $
engagio_get_tweet(tweet_id)	Get tweet details	FREE
engagio_get_thread(tweet_id)	Get full thread context	FREE

fetch_tweets parameters:

• username: Fetch single account only
• top_n: Limit to top N accounts by followers
• skip_recent_hours: Skip accounts fetched within X hours (default: 2)

Engagement

Tool	Description
engagio_post_reply(tweet_id, text, tone?)	Post a reply immediately
engagio_post_tweet(text)	Post original tweet
engagio_queue_reply(tweet_id, text)	Add reply to queue (15min spacing)
engagio_view_queue()	View pending replies
engagio_post_next()	Post next due reply
engagio_clear_queue()	Clear reply queue

Analytics

Tool	Description
engagio_get_reply_history(days?)	Your recent replies
engagio_update_reply_performance(days?)	Update engagement stats
engagio_get_analytics(days?)	Overall engagement analytics
engagio_get_account_roi(days?)	ROI per monitored account
engagio_get_timing_insights(days?)	Best posting times

Cost Optimization

Built-in Rate Limiting

• 3 second minimum between ALL API calls
• Auto-retry with exponential backoff (10s → 20s → 40s)
• last_fetched tracking to skip recently fetched accounts

Cost Estimates

Action	API Calls	Est. Cost
Top 10 fetch	10	~$0.015
Single account	1	~$0.0015
Cache search	0	FREE
Get opportunities	0	FREE

Best Practices

• Use fetch_tweets(top_n=10) for daily routine
• Use search_tweets(query, cache_only=True) to search cached data
• Let skip_recent_hours prevent duplicate fetches
• Only do full fetches (fetch_tweets()) when necessary

API Costs

• twitterapi.io: ~$0.0015 per API call
• Twitter API: Free tier (17 posts/day, 1,500/month cap)
• Supabase: Free tier

License

MIT