arnaldo-delisio/engagio-mcp

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

Topic Management

Tweet Discovery (Cost-Optimized)

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

Analytics

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

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