Roistat MCP Server

MCP (Model Context Protocol) сервер для интеграции с платформой маркетинговой аналитики Roistat. Позволяет AI-агентам (Claude, GPT и др.) напрямую работать с данными Roistat: анализировать статистику, управлять лидами, отслеживать звонки и каналы.

---

Возможности

📊 Аналитика

Инструмент	Описание
roistat_get_statistics	Маркетинговая статистика: визиты, лиды, ROI, CPL по каналам/кампаниям
roistat_get_report	Гибкий отчёт с группировкой по дням/неделям/месяцам

🎯 Лиды и заявки

Инструмент	Описание
roistat_list_leads	Список лидов с фильтрацией по дате, статусу
roistat_get_lead	Детальная информация о конкретном лиде
roistat_update_lead	Обновление статуса, выручки, полей лида
roistat_create_lead	Создание нового лида (оффлайн-конверсии)

📞 Коллтрекинг

Инструмент	Описание
roistat_list_calls	История звонков с фильтрацией
roistat_get_call	Детали звонка: источник, запись, длительность
roistat_list_phones	Список подменных номеров

📡 Рекламные каналы

Инструмент	Описание
roistat_list_channels	Все маркетинговые каналы проекта
roistat_get_channel_costs	Расходы по каналам за период
roistat_set_channel_costs	Ручная загрузка расходов (оффлайн-каналы)

⚙️ Проект

Инструмент	Описание
roistat_get_project_info	Информация о проекте, настройки, интеграции
roistat_list_events	Конверсионные события
roistat_send_event	Ручная отправка события конверсии
roistat_get_billing	Тариф, баланс, статистика использования
roistat_get_mediaplan	Медиаплан: план vs факт по каналам

---

Установка

Требования

• Node.js 18+
• npm или yarn
• Аккаунт Roistat с API-доступом

Шаги

git clone <repo-url>
cd roistat-mcp-server
npm install
npm run build

Переменные окружения

# Обязательные
ROISTAT_API_KEY=ваш_api_ключ        # Профиль → API-ключ
ROISTAT_PROJECT_ID=12345            # Номер проекта (из URL или настроек)

# Опциональные
TRANSPORT=stdio                     # или "http" для удалённого сервера
PORT=3000                           # только при TRANSPORT=http

Где найти API ключ: Roistat → Настройки → API-ключ → Скопировать

---

Запуск

stdio (локально, для Claude Desktop / Claude Code)

ROISTAT_API_KEY=xxx ROISTAT_PROJECT_ID=12345 node dist/index.js

HTTP (удалённое развёртывание, VPS/Docker)

TRANSPORT=http PORT=3000 ROISTAT_API_KEY=xxx ROISTAT_PROJECT_ID=12345 node dist/index.js

---

Конфигурация Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "roistat": {
      "command": "node",
      "args": ["/path/to/roistat-mcp-server/dist/index.js"],
      "env": {
        "ROISTAT_API_KEY": "ваш_api_ключ",
        "ROISTAT_PROJECT_ID": "12345"
      }
    }
  }
}

Конфигурация для HTTP (OpenClaw / удалённый MCP)

{
  "mcpServers": {
    "roistat": {
      "url": "http://your-vps-ip:3000/mcp",
      "type": "streamable-http"
    }
  }
}

---

Docker-деплой (для Hostinger VPS)

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 3000
ENV TRANSPORT=http
CMD ["node", "dist/index.js"]

docker build -t roistat-mcp .
docker run -d -p 3000:3000 \
  -e ROISTAT_API_KEY=xxx \
  -e ROISTAT_PROJECT_ID=12345 \
  roistat-mcp

---

Примеры запросов к Claude

После подключения MCP спрашивайте Claude:

• "Покажи ROI по каналам за последние 30 дней"
• "Сколько лидов пришло из Яндекс.Директ в марте?"
• "Найди все непринятые звонки за вчера и создай по ним задачи"
• "Загрузи расходы по оффлайн-каналу 500 рублей за сегодня"
• "Сравни CPL апреля с мартом по всем каналам"
• "Обнови статус лида #12345 на 'Оплачен', выручка 15000 руб"

---

Структура проекта

roistat-mcp-server/
├── src/
│   ├── index.ts              # Точка входа, инициализация сервера
│   ├── services/
│   │   └── roistat-client.ts # HTTP-клиент для Roistat API
│   └── tools/
│       ├── analytics.ts      # Статистика и отчёты
│       ├── leads.ts          # Лиды и заявки
│       ├── calltracking.ts   # Коллтрекинг
│       ├── channels.ts       # Каналы и расходы
│       └── project.ts        # Проект, события, биллинг
├── dist/                     # Скомпилированные файлы
├── package.json
└── tsconfig.json

---

Лицензия

MIT