# @ethioviral/mcp

MCP server for the [Ethio-Viral](https://ethio-viral.com) 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:

- [ethio-viral.com/api-keys](https://ethio-viral.com/api-keys)
- [store.ethio-viral.com/profile/api-keys](https://store.ethio-viral.com/profile/api-keys)
- the Telegram bot — send `/api`

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

## Install

### Claude Desktop

`claude_desktop_config.json`:

```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

```bash
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