Skip to main content
Glama
Sign In
@ethioviral/mcp

@ethioviral/mcp

by black12-ag
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

@ethioviral/mcp

MCP server for the Ethio-Viral partner API. Browse the live catalog and place orders from Claude Desktop, Cursor, or any MCP-capable client.

One API key opens all three product lines:

Store

gift cards, game top-ups, airtime and data

Premium

subscription seats at reseller pricing

SMM

followers, views, likes

Get a key

Create one in whichever place you already use — all three issue the same key:

The key is shown once. Full API reference: https://api.ethio-viral.com/docs/v1

Related MCP server: E-Commerce MCP Server

Install

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "ethio-viral": {
      "command": "npx",
      "args": ["-y", "@ethioviral/mcp"],
      "env": { "ETHIOVIRAL_API_KEY": "evk_YOUR_KEY" }
    }
  }
}

Cursor

.cursor/mcp.json, same shape.

Anything else

ETHIOVIRAL_API_KEY=evk_YOUR_KEY npx -y @ethioviral/mcp

Speaks MCP over stdio.

Configuration

Variable

Required

Default

ETHIOVIRAL_API_KEY

yes

—

ETHIOVIRAL_API_BASE_URL

no

https://api.ethio-viral.com

Tools

Store — search_catalog, list_categories, get_category, get_product, get_balance, create_order, get_order, get_order_history

Premium — list_premium_products, get_premium_product, get_premium_balance, create_premium_order, get_premium_order, get_premium_delivery

SMM — list_smm_services, create_smm_order, get_smm_order

Webhooks — get_webhook, set_webhook, delete_webhook, test_webhook

Money safety

Three tools spend real money: create_order, create_premium_order, create_smm_order.

  • Every order sends an Idempotency-Key. If you don't supply one a fresh UUID is generated per call, so an agent that retries a timed-out request cannot double-charge you. To retry a call you believe may have succeeded, pass the same idempotencyKey — that makes it the same purchase rather than a second one.

  • Confirm the target before ordering. A wrong phone number, game ID or SMM link delivers to someone else and cannot be recalled — the supplier fulfilled successfully, just to the wrong person.

  • This process moves no money itself. It makes HTTPS calls to api.ethio-viral.com; ordering, payment and fulfilment all stay server-side.

  • It holds no secret but your API key, read from the environment. Revoke a key from the same page you created it on.

A note on what you may sell

This server exposes what the API exposes. What you are allowed to sell depends on the host you connect it to, not on this package:

  • OpenAI's commerce policies prohibit several categories the API serves happily — social-media engagement, in-game currency, top-ups, and gift cards through an app's external checkout.

  • Anthropic's MCP directory policy has its own rules, including on financial transactions.

If you are publishing an integration on someone else's platform, read that platform's rules and point this server at a key scoped to what they permit. Do not rely on prompting a model to avoid listing a product — gate it server-side.

Licence

MIT

Available Tools

21 tools
create_orderBuy a productA

Places a live order, debited from your prepaid balance. denomination MUST exactly match one of the product's denoms[].retailMinor from get_product — call get_product first to get a current price, since prices can change. recipient is required when the product's recipientType is phone_number or email (E.164 digits, no leading + for phone). Moves real money — only call this once you intend to complete the purchase.

Inputs: productId (required), denomination (required), recipient, idempotencyKey.

create_premium_orderOrder a premium subscription (SPENDS MONEY)A

Buys a subscription seat and debits your USD wallet. Confirm the product, the price and the recipient with the user before calling this — it is not reversible from here. An Idempotency-Key is sent automatically, so retrying an identical call is safe and will never double-charge.

Inputs: productId (required), quantity, recipient, idempotencyKey.

create_smm_orderCreate an SMM order (SPENDS MONEY)A

Buys a social-media service and debits your wallet. CONFIRM THE LINK WITH THE USER FIRST — delivery goes to whatever link is given and cannot be recalled once the supplier accepts it. Quantity must be within the service min/max.

Inputs: link (required), quantity (required), serviceId (required), params, +1 more.

delete_webhookRemove your webhook endpointA

Stops webhook delivery. Orders are unaffected; you fall back to polling get_order.

Inputs: no named parameters.

get_balanceGet your prepaid balanceA

Returns the calling partner account's current prepaid balance (ETB). Orders are paid from this balance.

Inputs: no named parameters.

get_categoryList products in a categoryB

Returns every product in one category (from list_categories).

Inputs: category (required).

get_orderGet order statusA

Fetches the current status of one order by id — use this to re-check an order after create_order, or to recover from a timed-out call.

Inputs: orderId (required).

get_order_historyList your recent ordersA

Returns up to 50 of your most recent orders, newest first.

Inputs: no named parameters.

get_premium_balanceGet your premium (USD) balanceA

The USD wallet premium orders are debited from. Check this before ordering — an order with insufficient balance is refused with 402.

Inputs: no named parameters.

get_premium_deliveryCollect a premium deliveryA

The credentials, invite or link for a fulfilled premium order. Unlike store orders, premium delivery is NOT inline on the order — you must call this once status is fulfilled.

Inputs: orderId (required).

get_premium_orderGet one premium orderA

Status of a premium order. Poll this after create_premium_order, or to recover from a timed-out call.

Inputs: orderId (required).

get_premium_productGet one premium productA

Fetches one subscription product with its current tier price and stock — call this right before create_premium_order so you are quoting a live price.

Inputs: productId (required).

get_productGet product detailA

Fetches one product by id (from search_catalog / get_category), including its current live price — always call this right before create_order to get the exact denomination.

Inputs: productId (required).

get_smm_orderGet one SMM orderC

Status and real delivery progress (start count, delivered so far, remaining) for an SMM order.

Inputs: orderId (required).

get_webhookGet your webhook endpointA

The endpoint we POST order events to, with its recent delivery health. Returns null if none is configured.

Inputs: no named parameters.

list_categoriesList catalog categoriesA

Returns each product category (airtime, esim, giftcards, gaming, bills) with its item count.

Inputs: no named parameters.

list_premium_productsList premium subscription productsA

Subscription seats (design tools, AI tools, streaming) priced on your reseller tier. Separate catalog and separate USD wallet from the store, but the same API key opens both.

Inputs: no named parameters.

list_smm_servicesList SMM servicesA

Social-media services (followers, views, likes) with their rate per 1000 and min/max order size. There are ~7,500 services, so ALWAYS pass a query (e.g. "tiktok followers", "instagram likes") — an unfiltered list is enormous and mostly irrelevant. The min and max are enforced server-side; an order outside them is refused.

Inputs: limit, query.

search_catalogSearch the Ethio-Viral catalogA

Full-text search across airtime, eSIMs, gift cards, and game top-ups. Returns up to 50 matching products with live prices.

Inputs: query (required).

set_webhookSet your webhook endpointA

Registers an https endpoint we call on every terminal order state, so you can stop polling. RETURNS THE SIGNING SECRET EXACTLY ONCE — show it to the user and tell them to store it now; it can never be read back. Private, loopback and cloud-metadata addresses are refused.

Inputs: url (required), events.

test_webhookSend a signed test deliveryA

Posts a signed test event to the configured endpoint and reports what came back, so a partner can verify their signature check before relying on it.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 21 tools

    Disambiguation4/5

    Tools are generally distinguishable by domain prefix (store, premium, SMM, webhook), and descriptions clarify remaining ambiguity. A few pairs like get_order vs get_smm_order or list_premium_products vs get_premium_product could cause misselection if an agent skims names, but context usually resolves them.

    Naming Consistency5/5

    Every tool follows a consistent verb_noun pattern using list, search, get, create, set, delete, or test. Domain qualifiers such as premium, smm, and webhook are applied uniformly, making the set predictable and easy to navigate.

    Tool Count3/5

    At 21 tools, the server is at the upper edge of what feels comfortable, though the breadth is justified by covering store, premium, SMM, and webhook workflows. Each tool has a clear purpose, but the overall surface area is heavy compared to a typical focused MCP server.

    Completeness4/5

    The server covers the core reseller lifecycle well: product discovery, balance checks, order creation, order status retrieval, delivery retrieval, and webhook configuration across all order types. Minor gaps exist, such as no pagination for order history and no SMM-specific history listing, but they are workable and not severe.

    Resources

    Related MCP Connectors

    Related MCP Servers