# 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