# RetailCRM MCP Server

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/retailcrm-mcp)
[![Deploy on Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/aryazansev/retailcrm-mcp)

MCP (Model Context Protocol) сервер для интеграции с RetailCRM API. Позволяет Claude и другим AI-ассистентам получать доступ к заказам, клиентам и товарам из вашей CRM-системы.

## 🚀 Развернуть в интернете (1 минута)

**Рекомендация:** Railway - лучший бесплатный вариант
- ⚡ Кликните кнопку **"Deploy on Railway"** выше
- 🔑 Добавьте API ключи RetailCRM
- 🌐 Получите рабочий URL: `https://your-app.railway.app`
- 🎯 Используйте в AI Studio: `https://your-app.railway.app/manifest`

## 🚀 Быстрый старт

### Установка через npm

```bash
npm install -g retailcrm-mcp
```

### Или локальная установка

```bash
git clone https://github.com/yourusername/retailcrm-mcp.git
cd retailcrm-mcp
npm install
npm run build
```

## ⚙️ Настройка

### 1. Получите API ключ из RetailCRM

1. Войдите в свою панель RetailCRM
2. Перейдите в **Настройки** → **Интеграция** → **Ключи доступа к API**
3. Создайте новый ключ с правами на чтение заказов, клиентов и товаров
4. Скопируйте ключ

### 2. Создайте файл конфигурации

Создайте файл `~/.retailcrm-mcp/.env`:

```bash
mkdir -p ~/.retailcrm-mcp
cat > ~/.retailcrm-mcp/.env << 'EOF'
RETAILCRM_URL=https://your-account.retailcrm.ru
RETAILCRM_API_KEY=your_api_key_here
MCP_PORT=3002
EOF
```

Или просто создайте `.env` файл в папке проекта:

```env
RETAILCRM_URL=https://your-account.retailcrm.ru
RETAILCRM_API_KEY=your_api_key_here
MCP_PORT=3002
```

### 3. Настройка (2 варианта)

#### Вариант A: Claude Desktop (локально)

Откройте файл конфигурации Claude Desktop:

**macOS:**
```bash
~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%/Claude/claude_desktop_config.json
```

Добавьте:

```json
{
  "mcpServers": {
    "retailcrm": {
      "command": "retailcrm-mcp"
    }
  }
}
```

#### Вариант B: Внешний HTTP сервер (для AI Studio и других инструментов)

**Запуск HTTP сервера:**

```bash
npm run server
```

Сервер будет доступен на:
- Health: http://localhost:3002/health
- Manifest: http://localhost:3002/manifest  
- Tools: http://localhost:3002/tools

**Для AI Studio:**
1. Запустите сервер: `npm run server`
2. В AI Studio используйте URL: `http://localhost:3002/manifest`
3. AI Studio автоматически обнаружит все доступные инструменты

**Для других HTTP клиентов:**
```bash
# Получить список инструментов
curl http://localhost:3002/tools

# Проверить статус сервера
curl http://localhost:3002/health

# Получить манифест
curl http://localhost:3002/manifest
```

### 4. Перезапустите Claude Desktop (если используете вариант A)

Полностью закройте и откройте заново Claude Desktop.

## 💬 Использование

Теперь вы можете спрашивать Claude о данных из RetailCRM:

- *"Покажи последние 10 заказов"*
- *"Найди заказ номер 12345"*
- *"Покажи информацию о клиенте с email@example.com"*
- *"Сколько заказов у нас всего?"*
- *"Покажи товары из категории X"*

## 🛠️ Доступные инструменты

### Заказы
- `get_orders` - Получить список заказов (с фильтрацией и пагинацией)
- `get_order` - Получить информацию о конкретном заказе по ID
- `create_order` - Создать новый заказ

### Клиенты
- `get_customers` - Получить список клиентов
- `get_customer` - Получить информацию о клиенте по ID
- `create_customer` - Создать нового клиента
- `update_customer` - Обновить данные клиента

### Товары
- `get_products` - Получить список товаров
- `get_product` - Получить информацию о товаре по ID

### Справочники и статистика
- `get_statistics` - Получить статистику по заказам/клиентам
- `get_order_statuses` - Получить статусы заказов
- `get_delivery_types` - Получить типы доставки
- `get_payment_types` - Получить типы оплат
- `get_sites` - Получить сайты
- `get_order_history` - Получить историю изменений заказа
- `get_tasks` - Получить список задач
- `create_task` - Создать задачу

## 🔧 Разработка

### Сборка проекта

```bash
npm run build
```

### Запуск в режиме разработки

```bash
# Для Claude Desktop (stdio)
npm run dev

# Для внешнего HTTP сервера (AI Studio)
npm run server
```

### Тестирование через MCP Inspector

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

### Тестирование HTTP сервера

```bash
# Запустить сервер
npm run server

# Проверить эндпоинты в другой терминал
curl http://localhost:3002/health
curl http://localhost:3002/manifest
curl http://localhost:3002/tools
```

## 📝 Требования

- Node.js 18+
- API ключ от RetailCRM
- Claude Desktop (для интеграции с Claude)

## 📄 Лицензия

MIT License - см. файл [LICENSE](LICENSE)

## 🤝 Поддержка

Если у вас возникли проблемы:

1. Проверьте, что API ключ активен и имеет нужные права
2. Убедитесь, что URL RetailCRM указан правильно (без слэша в конце)
3. Проверьте логи Claude Desktop
4. Создайте issue на GitHub

## 🔗 Ссылки

- [RetailCRM API Documentation](https://docs.retailcrm.ru/Developers/API/APIMethods)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)