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