sweb-mcp — MCP-сервер для управления хостингом SpaceWeb через языковую модель
📂 Исходный код на GitHubMCP-сервер (stdio, Python) для API SpaceWeb: 276 методов хостинга как tools для LLM, с трёхуровневой защитой и поддержкой нескольких аккаунтов.
sweb-mcp — это MCP-сервер на Python, который открывает клиентский API хостинг-провайдера SpaceWeb (sweb.ru) языковой модели. API построен на JSON-RPC 2.0 и охватывает 29 объектов и 276 уникальных методов: сайты, домены, DNS, VPS, почта, тарифы, платежи. Сервер превращает все эти методы в MCP-инструменты, поэтому вместо сценария «прочитай документацию и напиши curl» модель просто видит готовые tools и вызывает их.
Сервер работает по stdio и запускается любым MCP-клиентом по требованию: Claude Code, OpenCode, Cursor. Проект неофициальный и не связан со SpaceWeb; лицензия — MIT.
Что умеет
Типовой запрос к хостингу превращается в пару вызовов инструментов:
> сколько сейчас сайтов на аккаунте и которые из них без SSL?
sites_index → 7 сайтов
sites_getSiteInfo(siteId=...) → ...
Несколько примеров read-вызовов:
| Запрос | Вызов |
|---|---|
| Список сайтов | sites_index |
| Баланс и платежи | pay_index, pay_getBalance |
| DNS-записи домена | domains_dns_info(domain="example.ru") |
| VPS-серверы | vps_index |
| Почтовые ящики | vh_mail_getMailboxesList(domain="example.ru") |
| Текущий тариф | tariff_index |
Ответы API отдаются как есть, в формате JSON, без преобразований и кеширования.
Как устроены инструменты
Каждый метод API становится tool с именем вида <объект>_<метод>: sites_index, vps_index, domains_dns_editTxt, vh_mail_createMbox. Поверх них работают пять мета-инструментов:
sweb_list_methods— обзор и поиск методов по группе или подстроке;sweb_describe— описание конкретного метода: путь, параметры, семантика;sweb_call— прямой вызов любого метода, даже без отдельного tool;sweb_accounts— список аккаунтов и текущий аккаунт;sweb_use_account— переключение аккаунта по умолчанию до перезапуска.
Типовой поток для модели: сначала sweb_list_methods, затем sweb_describe, затем вызов нужного tool с параметрами.
Установка
Нужен Python 3.11–3.13. Пакет в PyPI не публикуется, ставится из git, из клона или из Docker-образа на GHCR:
uvx --from git+https://github.com/avert/sweb-mcp sweb-mcp
docker run -i --rm --env-file .env ghcr.io/avert/sweb-mcp:latest
Подключение к Claude Code:
claude mcp add sweb -- uv run --directory "$PWD" --env-file .env sweb-mcp
Пример конфигурации для Cursor (.cursor/mcp.json), установка без клонирования:
{
"mcpServers": {
"sweb": {
"command": "uvx",
"args": ["--from", "git+https://github.com/avert/sweb-mcp", "sweb-mcp"],
"env": { "SWEB_ACCOUNTS_FILE": "/path/to/accounts.json", "SWEB_ACCOUNT": "main" }
}
}
}
Для OpenCode настройка аналогична — блок mcp в opencode.json с командой uv run.
Безопасность: три уровня доступа
Каждый метод классифицируется как read, write, destructive или paid. Доступ включается ступенями:
- read — выполняется свободно;
- write — нужен
SWEB_READONLY=0и явныйconfirm=trueв аргументах tool; - destructive и paid — дополнительно
SWEB_ALLOW_DESTRUCTIVE=1.
В спеках API нет флагов read/write, поэтому класс выводится по эвристике: из имени метода, таблицы платных операций и ручных правок через SWEB_OVERRIDES. Метки [WRITE], [DESTRUCTIVE], [PAID] видны в описании tool — их стоит проверять перед включением записей.
Отдельная деталь защиты: авто-повторы после ошибок 502/503/504 и сбоев сети выполняются только для read-методов. Исход записи после такого сбоя неизвестен, а повтор мог бы задвоить заказ или удаление. Для ошибки 429 (превышен лимит запросов) повторы включены всегда — с экспоненциальной паузой и учётом заголовка Retry-After.
Аккаунты и учётные данные
Единственный источник учётных данных — JSON-файл из переменной SWEB_ACCOUNTS_FILE. Внутри — карта аккаунтов вида {"имя": {"login": "...", "password": "..."}} или {"имя": "login:password"}. Файлу нужны права chmod 600, и он не должен попадать в git — .gitignore уже исключает accounts*.json и .env.
Аккаунт по умолчанию задаёт SWEB_ACCOUNT. Токен кешируется на каждый аккаунт, а при истечении сессии (ошибка -32603) клиент перелогинивается автоматически.
Полезные переменные окружения:
| Переменная | Назначение | По умолчанию |
|---|---|---|
SWEB_READONLY |
только read-методы | 1 |
SWEB_ALLOW_DESTRUCTIVE |
разрешить destructive и paid | 0 |
SWEB_GROUPS |
фильтр групп, например vps,domains,vh/mail |
все |
SWEB_OVERRIDES |
JSON с ручной правкой классов, например {"/vps:reboot":"write"} |
— |
SWEB_MAX_CONCURRENCY, SWEB_MIN_INTERVAL |
защита от rate limit: одновременные запросы и пауза | 4, 0.2 с |
SWEB_MAX_RETRIES, SWEB_BACKOFF_BASE |
число повторов и база паузы | 3, 0.5 с |
Ограничения и типовые проблемы
О чём стоит знать до внедрения:
- Спеки — это снапшот. Файлы
specs/*.jsonсняты с apidoc.sweb.ru на момент синхронизации; официальной машиночитаемой спеки у SpaceWeb нет. Спеки в формате OpenRPC извлечены из JS-бандла документации, логика портирована из sanchpet/sweb-go-sdk. Обновление — скриптscripts/sync_specs.py. - Классификация эвристическая. Ошибка возможна, поэтому перед разрешением записей проверяйте метки в описании tool.
- Лимиты API не документированы. Настройки одновременных запросов и пауз подобраны с запасом; при 429 увеличивайте
SWEB_MIN_INTERVAL. - Сервер «молчит» в клиенте. Это норма для stdio: логи идут в stderr. При ручном запуске печатается строка
[sweb-mcp] readonly=… creds=set/MISSING. - Прокси не поддерживается через переменные окружения. Клиент ходит напрямую и игнорирует
HTTP(S)_PROXY; прокси настраивается на сетевом уровне (VPN или обёртка).
Лицензия
Проект распространяется по лицензии MIT. Это неофициальный клиент: автор не связан со SpaceWeb, гарантий не даёт и не отвечает за последствия вызовов, выполненных с вашими учётными данными. Используя сервер, вы соблюдаете условия обслуживания SpaceWeb и лимиты API. Подробности для контрибьюторов — в CONTRIBUTING.md, история изменений — в GitHub Releases.
Источник: https://github.com/AVert/sweb-mcp