Engagio

Engagio MCP provides a Python-based MCP server that enables Twitter engagement intelligence for Claude Code. It monitors accounts and topics, scores opportunities, posts replies, and tracks performance with timing insights, helping you engage more effectively and measure ROI.

How to use

Use this MCP server from your MCP client to monitor Twitter activity, discover high-value engagement opportunities, and automate thoughtful replies. You will fetch tweets from monitored accounts and topics, get ranked opportunities by engagement velocity and author reach, queue replies with spacing, and routinely review analytics to optimize your outreach.

Typical workflow statements you can issue include adding accounts to monitor, adding topics, fetching opportunities, generating reply options, queueing replies, posting replies, and reviewing analytics. You can tailor fetches to be cost-efficient by selecting top accounts or specific usernames, and you can inspect cached results for quick insight without extra costs.

How to install

Prerequisites: you need Python and a virtual environment, plus access to the required API tokens and database. You will run the MCP server locally and connect it to Claude Code.

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

Configuration and startup

Configure the MCP server to run locally and connect to the Twitter API, twitterapi.io for reading, and Supabase for storage. You will also expose the server to Claude Code via an MCP JSON entry.

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

Environment variables to configure

You need API credentials and database keys to enable publishing and data access. Use the following environment variables when you run the MCP server:

# 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

Notes on usage

Start the MCP server using the Python interpreter inside the virtual environment and point it to the server script. Ensure Claude Code is configured to load the MCP from the provided stdio configuration. Maintain proper security by keeping API keys secure and rotating credentials as needed.

Troubleshooting and tips

If you encounter rate-limiting or timeouts, rely on built-in delay controls to respect the 3-second minimum between API calls and use exponential backoff for retries. Check last_fetched timestamps to avoid refetching recently seen accounts and adjust skip_recent_hours as needed to reduce unnecessary fetches.

For performance analysis, review timing insights to identify the best posting windows, and use ROI metrics to fine-tune which accounts to prioritize. If you see unexpected engagement drops, verify that token scopes are correct and that the reading and writing APIs have the required permissions.

Available tools

engagio_add_account

Monitor a Twitter account and auto-fetch its bio for context.

engagio_add_accounts_bulk

Add multiple accounts with rate limit handling.

engagio_remove_account

Stop monitoring a single Twitter account.

engagio_remove_accounts_bulk

Remove multiple accounts from monitoring.

engagio_list_accounts

List monitored accounts with bios and notes.

engagio_backfill_bios

Fetch bios for accounts missing bios.

engagio_update_account_notes

Add or update notes for an account.

engagio_add_topic

Monitor a hashtag or keyword topic.

engagio_remove_topic

Stop monitoring a topic.

engagio_list_topics

List monitored topics.

engagio_fetch_topic_tweets

Fetch tweets for a given topic.

engagio_fetch_tweets

Fetch tweets from accounts with various scope controls.

engagio_get_opportunities

Get ranked engagement opportunities with filters (cost-free with cache).

engagio_search_tweets

Search tweets either from cache or live Twitter API.

engagio_get_tweet

Get details for a specific tweet.

engagio_get_thread

Get full thread context for a tweet.

engagio_post_reply

Post a reply immediately to a tweet.

engagio_post_tweet

Post an original tweet.

engagio_queue_reply

Queue a reply to be posted with spacing.

engagio_view_queue

View pending replies in the queue.

engagio_post_next

Post the next due reply from the queue.

engagio_clear_queue

Clear all replies from the queue.

engagio_get_reply_history

View recent replies for analytics.

engagio_update_reply_performance

Update engagement performance stats.

engagio_get_analytics

Get overall engagement analytics.

engagio_get_account_roi

Get ROI per monitored account.

engagio_get_timing_insights

Get timing insights for optimal posting