# 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
```bash
cd engagio-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### 2. Configure environment
Create `.env` file:
```env
# 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:
```sql
-- 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`:
```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
