# Rally MCP Server — Marketplace Affiliate Tools

**The first Model Context Protocol (MCP) server for Mercado Libre & Shopee affiliates.**

Built by [André Hocsis](https://andrehocsis.com.br) — Creator of [Rally de Vendas](https://rallydevendas.com.br), the leading AI-powered platform for Brazilian e-commerce sellers and affiliates.

---

## What is this?

An MCP server that gives AI assistants (Claude, ChatGPT, Cursor, etc.) direct access to marketplace affiliate tools:

- **Search products** on Mercado Libre and Shopee with commission estimates
- **Generate affiliate links** with tracking
- **Analyze products** (quality score 0-100, photos, title, price competitiveness)
- **Generate marketing copy** for TikTok, Reels, WhatsApp, Telegram, Blog
- **Check trending products** by category and season

## Why?

Mercado Libre has **no affiliate API**. Shopee's API is complex. This MCP server abstracts both into a simple, unified interface that any AI agent can use.

## Quick Start

```bash
# Install
npm install @rally-vendas/mcp-server

# Or run directly
npx @rally-vendas/mcp-server
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rally-affiliates": {
      "command": "npx",
      "args": ["@rally-vendas/mcp-server"],
      "env": {
        "ML_AFFILIATE_ID": "your_matt_tool_id",
        "SHOPEE_APP_ID": "your_app_id",
        "SHOPEE_SECRET": "your_secret"
      }
    }
  }
}
```

## Available Tools

### `search_products`
Search products across marketplaces with affiliate commission estimates.

```json
{
  "marketplace": "mercadolibre",
  "query": "fone bluetooth",
  "category": "MLB1051",
  "sort": "relevance",
  "limit": 20
}
```

**Returns:** Product list with title, price, image, commission rate, estimated earnings, affiliate link.

### `generate_affiliate_link`
Generate a tracked affiliate link for any product.

```json
{
  "marketplace": "mercadolibre",
  "product_url": "https://www.mercadolivre.com.br/produto-xyz/p/MLB12345",
  "campaign": "tiktok_maio"
}
```

**Returns:** Affiliate URL with tracking parameters.

### `analyze_product`
Get a quality score (0-100) for any marketplace product.

```json
{
  "marketplace": "mercadolibre",
  "product_id": "MLB12345"
}
```

**Returns:** Score breakdown (title, photos, description, attributes, price), problems found, improvement suggestions.

### `generate_copy`
AI-powered marketing copy for any channel.

```json
{
  "product_id": "MLB12345",
  "channel": "tiktok",
  "tone": "casual",
  "language": "pt-BR"
}
```

**Returns:** Ready-to-post copy with hashtags, emojis, and CTA.

### `trending_products`
Get trending products by category with commission data.

```json
{
  "marketplace": "mercadolibre",
  "category": "MLB1051",
  "period": "7d"
}
```

**Returns:** Top products by sales velocity, with commission estimates.

### `commission_calculator`
Calculate expected earnings for a product.

```json
{
  "marketplace": "mercadolibre",
  "product_id": "MLB12345",
  "estimated_daily_clicks": 50,
  "conversion_rate": 0.02
}
```

**Returns:** Daily/monthly/yearly estimated commission in BRL.

## Supported Marketplaces

| Marketplace | Search | Links | Analytics | Reports |
|---|---|---|---|---|
| **Mercado Libre** (Brazil) | ✅ | ✅ (matt_tool) | ✅ (Raio-X) | Estimated |
| **Shopee** (Brazil) | ✅ | ✅ (API) | ✅ | ✅ Real-time |
| Amazon (coming soon) | ⏳ | ⏳ | ⏳ | ⏳ |

## Architecture

```
rally-mcp-server/
├── src/
│   ├── index.ts              — MCP server entry point
│   ├── tools/
│   │   ├── search.ts         — Product search (ML + Shopee)
│   │   ├── links.ts          — Affiliate link generation
│   │   ├── analyze.ts        — Product analysis (Raio-X)
│   │   ├── copy.ts           — AI copy generation
│   │   └── trending.ts       — Trending products
│   ├── adapters/
│   │   ├── mercadolibre.ts   — ML API adapter
│   │   └── shopee.ts         — Shopee API adapter
│   └── utils/
│       ├── commission.ts     — Commission calculator
│       └── cache.ts          — Request caching
├── package.json
├── tsconfig.json
└── README.md
```

## Built With

- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) — Anthropic's MCP
- [Mercado Libre API](https://developers.mercadolibre.com) — Product data
- [Shopee Affiliate API](https://www.affiliateshopee.com.br/documentacao) — Affiliate operations

## About Rally de Vendas

[Rally de Vendas](https://rallydevendas.com.br) is a Brazilian AI-powered e-commerce platform that helps:

- **Sellers**: Manage Mercado Libre listings with AI optimization, Raio-X diagnostics, bulk management
- **Affiliates**: Discover products, generate tracked links, create content with AI, automate WhatsApp/Telegram
- **Agencies**: Multi-account management, centralized inbox, dynamic pricing

**500+ routes · 90+ controllers · AI-powered (Claude + Gemini) · ISO 9001 + 27001 compliant**

## Author

**André Hocsis** — E-commerce specialist, AI developer, creator of Rally de Vendas.

- Website: [andrehocsis.com.br](https://andrehocsis.com.br)
- Platform: [rallydevendas.com.br](https://rallydevendas.com.br)
- Affiliates: [afiliados.rallydevendas.com.br](https://afiliados.rallydevendas.com.br)

## License

MIT — Free to use, modify, and distribute. Attribution appreciated.

---

**⭐ Star this repo if you find it useful! First MCP server for marketplace affiliates in Brazil.**