engain-mcp

An MCP server that wraps the Engain v1 API, so Claude Code and other MCP clients can drive Engain — Reddit growth campaigns, tasks, upvote/downvote orders, opportunity & mention discovery — programmatically.

It's a thin, hand-authored wrapper over Engain's documented REST API. Each endpoint becomes an MCP tool with a typed input schema and an agent-friendly description, so an LLM agent can discover projects, scan opportunities, draft and schedule tasks, place upvote orders, and read account state — all through one connected MCP server.

Quick start (Claude Code)

Add the server to your MCP config (~/.claude.json, or a project .mcp.json):

{
  "mcpServers": {
    "engain": {
      "command": "npx",
      "args": ["-y", "engain-mcp"],
      "env": {
        "ENGAIN_API_KEY": "eng_your_key_here",
        "ENGAIN_PROJECT_ID": "optional-default-project-id",
        "ENGAIN_MCP_READONLY": "false"
      }
    }
  }
}

Generate your ENGAIN_API_KEY in the Engain app under Settings → API (MAX-plan workspace). Restart your MCP client and the engain_* tools become available.

Configuration

Env var	Required	Default	Purpose
ENGAIN_API_KEY	✅	—	Your Engain API key (eng_…). Sent as the X-API-Key header.
ENGAIN_BASE_URL		https://api.engain.io	API host. Point at a non-prod deployment for testing.
ENGAIN_PROJECT_ID		—	Default project ID for project-scoped tools when one isn't passed.
ENGAIN_MCP_READONLY		false	When truthy (1/true/yes), all credit-spending tools are hidden.

Spend safety

Six tools spend credits: engain_create_comment_task, engain_create_post_task, engain_create_reply_task, engain_create_thread_task_group, engain_create_upvote_order, engain_create_downvote_order.

Set ENGAIN_MCP_READONLY=true and those six are never registered — the agent sees only the 23 read-only tools. With spending enabled, each spend tool returns the credits charged and remaining balance in its result, so the agent always sees what it just spent.

Tools (29)

Every tool is prefixed engain_. Project-scoped tools take an optional projectId that falls back to ENGAIN_PROJECT_ID; call engain_get_me to discover project IDs.

Account

• engain_get_me — current user + accessible projects
• engain_get_balance — remaining credits and free comments
• engain_list_credit_transactions — paginated credit history

Tasks (read)

• engain_list_tasks, engain_get_task, engain_get_tasks_bulk
• engain_get_rank_metrics — recommended upvote metrics for a URL (no credits; 5 req/min)

Tasks (spend 💳)

• engain_create_comment_task, engain_create_post_task, engain_create_reply_task, engain_create_thread_task_group

Orders (read)

• engain_list_orders, engain_get_order, engain_get_orders_bulk

Orders (spend 💳)

• engain_create_upvote_order, engain_create_downvote_order

Discovery

• engain_list_opportunities, engain_get_opportunity
• engain_list_mentions, engain_get_mention, engain_get_mention_stats, engain_get_mention_brands

Labels

• engain_list_labels, engain_create_label, engain_delete_label
• engain_add_task_labels, engain_remove_task_labels, engain_add_order_labels, engain_remove_order_labels

How it works

• X-API-Key auth on every request; the base path is always /api/v1.
• Project resolution — project-scoped tools use the call's projectId, else ENGAIN_PROJECT_ID, else return a clear error pointing you at engain_get_me.
• Resilient errors — non-2xx responses become structured errors (status, code, message); 429 rate limits are retried automatically with backoff (honoring Retry-After, up to 3 attempts).
• Transport — stdio today; the tool/client layer is transport-agnostic so a remote (HTTP) transport can be added without touching tools.

Development

npm install
npm test          # vitest unit suite
npm run typecheck # tsc --noEmit (vitest does not typecheck)
npm run build     # emits dist/ (tests excluded from the package)

Architecture: src/config.ts (env) → src/client.ts (EngainClient/EngainError) → src/tools/* (one module per domain; each tool is an EngainTool made with defineTool) → src/tools/index.ts (buildToolRegistry, applies the readonly filter) → src/server.ts / src/bin.ts (MCP stdio wiring). Tools are plain data objects, so the whole surface is unit-testable without the MCP SDK.

License

MIT