Skip to main content
Glama
engain-mcp

engain-mcp

by EngainDev

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.

node types license

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.

Related MCP server: Reddit MCP Server

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

Available Tools

29 tools
engain_add_order_labelsB

Add one or more labels to an order.

Inputs: labels (required), orderId (required).

engain_add_task_labelsC

Add one or more labels to a task.

Inputs: labels (required), taskId (required).

engain_create_comment_taskC

Create a Reddit comment task on a thread URL. SPENDS CREDITS (typically 5).

Inputs: url (required), content (required), rank, labels, +2 more.

engain_create_downvote_orderB

Create a downvote order on a Reddit post or comment. SPENDS CREDITS.

Inputs: url (required), target (required), quantity (required), labels, +3 more.

engain_create_labelC

Create a new label in a project.

Inputs: name (required), projectId.

engain_create_post_taskC

Create a Reddit post task in a subreddit. SPENDS CREDITS (typically 10).

Inputs: content (required), postTitle (required), subredditUrl (required), rank, +3 more.

engain_create_reply_taskB

Create a Reddit reply task to a specific comment URL. SPENDS CREDITS (typically 5).

Inputs: url (required), content (required), rank, labels, +2 more.

engain_create_thread_task_groupA

Create a threaded group of tasks (a parent task plus child replies). SPENDS CREDITS per task in the group.

Inputs: parentTask (required), labels, projectId, childTasks.

engain_create_upvote_orderB

Create an upvote order on a Reddit post or comment. SPENDS CREDITS (~0.1 per vote).

Inputs: url (required), target (required), quantity (required), labels, +3 more.

engain_delete_labelB

Delete a label from a project by name.

Inputs: labelName (required), projectId.

engain_get_balanceA

Get remaining credits and free comments for the authenticated Engain workspace.

Inputs: no named parameters.

engain_get_meA

Get the current Engain user and the list of projects (campaigns) they can access. Use this first to discover projectId values for other tools.

Inputs: no named parameters.

engain_get_mentionC

Get a single mention by ID.

Inputs: mentionId (required).

engain_get_mention_brandsB

Get per-brand mention counts for a project.

Inputs: projectId.

engain_get_mention_statsA

Get aggregated sentiment counts for a project's mentions, optionally for one brand.

Inputs: brand, projectId.

engain_get_opportunityC

Get a single opportunity by ID.

Inputs: opportunityId (required).

engain_get_orderC

Get a single order by ID.

Inputs: orderId (required).

engain_get_orders_bulkB

Fetch up to 100 orders by ID in one call.

Inputs: ids (required), projectId.

engain_get_rank_metricsA

Get recommended upvote metrics for a Reddit post or comment URL. Rate-limited to 5 requests/minute. Does not spend credits.

Inputs: url (required), type (required).

engain_get_taskA

Get a single task by ID. Set refreshMetrics to pull live upvote/reply counts.

Inputs: taskId (required), refreshMetrics.

engain_get_tasks_bulkA

Fetch up to 100 tasks by ID in one call.

Inputs: ids (required), projectId.

engain_list_credit_transactionsA

List credit transaction history for a project (newest first), paginated via cursor.

Inputs: type, cursor, numItems, projectId, +2 more.

engain_list_labelsB

List all labels defined in a project.

Inputs: projectId.

engain_list_mentionsC

List brand mentions discovered for a project, filterable by brand and sentiment.

Inputs: brand, cursor, sortBy, numItems, +2 more.

engain_list_opportunitiesB

List discovered opportunities for a project. type selects new Reddit opportunities or SEO opportunities.

Inputs: type (required), cursor, sortBy, numItems, +1 more.

engain_list_ordersA

List a project's upvote/downvote orders, paginated. Filter by status OR campaignId (not both).

Inputs: cursor, status, numItems, projectId, +3 more.

engain_list_tasksA

List a project's tasks (comments/posts/replies), newest first, paginated via cursor.

Inputs: cursor, status, numItems, projectId, +2 more.

engain_remove_order_labelsC

Remove one or more labels from an order.

Inputs: labels (required), orderId (required).

engain_remove_task_labelsC

Remove one or more labels from a task.

Inputs: labels (required), taskId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 29 tools

    Disambiguation5/5

    Every tool targets a specific action on a distinct resource (labels, tasks, orders, mentions, opportunities, credits). Even bulk versions are clearly separated from single-item tools. No overlapping purposes.

    Naming Consistency5/5

    All tools follow a uniform 'engain_verb_noun' pattern in snake_case, with verbs like add, create, delete, get, list, remove. No mixing of styles or naming conventions.

    Tool Count4/5

    29 tools is on the higher side but well-justified by the breadth of the domain (labels, tasks, orders, mentions, opportunities, credits). The tools are grouped by resource, making the set manageable.

    Completeness3/5

    The set covers creation and retrieval for most resources but lacks update and delete for tasks and orders. Labels are fully covered. Gaps exist for modifying or removing core entities.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides access to Reddit's API for retrieving posts, comments, user information, and search functionality. Supports multiple authentication methods and comprehensive Reddit data operations including subreddit browsing, post retrieval, and user profile access.
      9
      1,938 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with Reddit through a comprehensive API interface supporting both read-only operations (browsing posts, comments, user profiles) and authenticated actions (posting, commenting, voting) via OAuth2 authentication.
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Instagram engagement analysis using the unofficial Instagram Private API, including comment sentiment analysis, account comparison, demographic extraction, lead identification, and engagement reporting.
      67 npm
      MIT