快递计算与订单管理服务器

CDEK MCP Server

MCP (Model Context Protocol) сервер для интеграции с API СДЭК. Позволяет Claude, AI Studio и другим AI-ассистентам рассчитывать стоимость доставки, создавать заказы и отслеживать отправления.

🚀 Быстрое развертывание (1 минута)

Рекомендация: Railway - лучший бесплатный вариант

• ⚡ Кликните кнопку "Deploy on Railway" выше
• 🔑 Добавьте CDEK_CLIENT_ID и CDEK_CLIENT_SECRET
• 🌐 Получите рабочий URL: https://your-app.railway.app
• 🎯 Используйте в AI Studio: https://your-app.railway.app/manifest

📦 Установка

Через npm

npm install -g cdek-mcp

Локальная установка

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

⚙️ Настройка

1. Получите учетные данные от СДЭК

1. Заключите договор со СДЭК или запросите тестовые доступы
2. Получите Client ID и Client Secret в личном кабинете
3. Для тестового окружения: https://api.edu.cdek.ru/v2

2. Варианты использования

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

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

macOS:

mkdir -p ~/.cdek-mcp
cat > ~/.cdek-mcp/.env << 'EOF'
CDEK_CLIENT_ID=your_client_id
CDEK_CLIENT_SECRET=your_client_secret
CDEK_BASE_URL=https://api.cdek.ru/v2
EOF

Откройте ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cdek": {
      "command": "cdek-mcp"
    }
  }
}

Вариант B: Внешний HTTP сервер (для AI Studio)

Локальный запуск:

# Создайте .env файл
export CDEK_CLIENT_ID=your_client_id
export CDEK_CLIENT_SECRET=your_client_secret

# Запустите HTTP сервер
npm run server

Сервер будет доступен:

• Health: http://localhost:3003/health
• Manifest: http://localhost:3003/manifest
• Tools: http://localhost:3003/tools

Для AI Studio:

1. Запустите сервер или разверните на Railway/Render
2. В AI Studio используйте URL: http://localhost:3003/manifest (или ваш URL деплоя)
3. AI Studio автоматически обнаружит все доступные инструменты

3. Перезапустите Claude Desktop

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

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

Теперь вы можете спрашивать Claude:

• "Рассчитай доставку из Москвы в Санкт-Петербург, посылка 1 кг"
• "Найди ближайшие ПВЗ в Москве"
• "Отследи заказ по номеру 1234567890"
• "Создай заказ на доставку тарифом посылка склад-дверь"
• "Покажи все доступные тарифы СДЭК"
• "Закажи курьера на завтра с 10 до 18 часов"

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

Калькулятор доставки

• calculate_delivery - Рассчитать стоимость и сроки по конкретному тарифу
• calculate_delivery_all_tariffs - Рассчитать по всем доступным тарифам
• get_tariffs - Получить список тарифов

Управление заказами

• create_order - Создать заказ на доставку
• get_order - Получить заказ по UUID
• get_order_by_cdek_number - Найти заказ по номеру СДЭК
• get_orders_list - Получить список заказов
• delete_order - Удалить заказ

ПВЗ и локации

• get_pickup_points - Поиск пунктов выдачи заказов
• get_cities - Справочник городов
• get_regions - Справочник регионов

Курьер

• create_courier_pickup - Заказать курьера на забор
• get_courier_pickup - Информация о заборе

Отслеживание и услуги

• track_order - Отследить отправление
• get_services - Список дополнительных услуг

🌐 HTTP API

При развертывании HTTP сервера доступны эндпоинты:

# Проверка работоспособности
GET /health

# MCP Manifest
GET /manifest

# Список инструментов
GET /tools

# Выполнение инструмента
POST /tools/:toolName
Content-Type: application/json

# Пример:
POST /tools/calculate_delivery
{
  "tariff_code": 136,
  "from_location": {"code": 44},
  "to_location": {"code": 137},
  "packages": [{"weight": 1000}]
}

🔧 Разработка

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

npm run build

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

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

# Для HTTP сервера
npm run server

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

npx @modelcontextprotocol/inspector node build/index.js

📚 Документация

• Инструкция по развертыванию
• Документация CDEK API
• MCP Protocol

📝 Требования

• Node.js 18+
• Учетные данные API СДЭК (Client ID и Client Secret)

📄 Лицензия

MIT License - см. файл LICENSE

🤝 Поддержка

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

1. Проверьте, что учетные данные API верны
2. Убедитесь, что у вас активен договор со СДЭК (для production)
3. Проверьте логи в панели деплоя или консоли
4. Создайте issue на GitHub

🔗 Ссылки

• NPM Package
• GitHub Repository
• Документация СДЭК