timeweb-mcp

MCP-сервер для Timeweb Cloud: управление облачными серверами, доменами, DNS-записями и просмотр баланса из Claude (Desktop, Code, Cowork) и любых других MCP-клиентов.

MCP (Model Context Protocol) — открытый протокол, через который AI-ассистенты подключаются к внешним сервисам. Этот сервер даёт ассистенту руки для вашей инфраструктуры в Timeweb Cloud: «покажи баланс», «какой статус у сервера», «добавь A-запись для нового поддомена» — без захода в панель.

Эндпоинты сверены с официальным sdk-javascript. Не аффилирован с Timeweb.

Возможности

Группа	Инструменты
Аккаунт	account_status, account_finances (баланс и прогноз списаний)
Серверы	list_servers, get_server, get_server_logs, list_server_presets, list_os_images, server_power⚠️, create_server⚠️💰, delete_server⚠️☠️
Домены и DNS	list_domains, get_domain, get_name_servers, list_dns_records, create_dns_record, update_dns_record, delete_dns_record⚠️
SSH	server_diagnostics (read-only осмотр), service_control⚠️ (systemctl), ssh_exec⚠️ (любая команда)

В плагин входит скилл timeweb-ops — инструкция для ассистента: типовые сценарии (подключить домен к серверу, поднять VPS, следить за балансом), протокол подтверждений и обработка ошибок. Срабатывает сам на фразы вроде «покажи мои серверы» или «добавь A-запись».

Безопасность встроена в инструменты:

• ⚠️ — операция выполняется только с явным параметром confirm: true; без него ассистент получает отказ и должен переспросить вас.
• ☠️ — delete_server дополнительно требует expected_name: имя сверяется с реальным именем сервера, и при несовпадении удаление отклоняется. Защита от «удалил не тот id».
• Токен хранится в файле с правами 600 и не передаётся через аргументы команд (не светится в списке процессов).

Установка как плагин Claude (самый простой способ)

Плагин ставится прямо из git — токен настраивается один раз (см. Токен API):

/plugin marketplace add https://github.com/<your-name>/timeweb-mcp
/plugin install timeweb-mcp@k2spam-tools

Внутри плагина — самодостаточный бандл (mcp/server.cjs), ничего собирать и устанавливать не нужно. Альтернатива: скачать готовый build/timeweb-mcp-v<версия>.plugin из релизов и установить файлом (Cowork: перетащить в чат → Save plugin).

Установка вручную (как обычный MCP-сервер)

Требования: Node.js ≥ 18.

git clone https://github.com/<your-name>/timeweb-mcp.git
cd timeweb-mcp
npm install
npm run build

1. Токен API

Панель Timeweb Cloud → API и Terraform → создать токен.

Токен кладётся на диск один раз, дальше сервер находит его сам:

macOS / Linux:

mkdir -p ~/.config/timeweb-mcp
# вставьте токен (например, из буфера обмена):
cat > ~/.config/timeweb-mcp/token   # вставить, затем Ctrl+D
chmod 600 ~/.config/timeweb-mcp/token

Windows (PowerShell):

New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\timeweb-mcp"
Set-Content "$env:USERPROFILE\.config\timeweb-mcp\token" "<ваш токен>"

Для отладки можно переопределить файл переменной окружения TIMEWEB_CLOUD_TOKEN.

1b. SSH-доступ к серверам

Инструменты server_diagnostics / service_control / ssh_exec ходят на серверы по SSH. Настраивать ничего не нужно:

• Адрес не обязателен. Достаточно назвать сервер по имени (nanospace-node-de) или id — IP подтянется через API по вашему токену. IP/домен тоже можно передать напрямую.
• Ключ искать не нужно. Коннектор находит все приватные ключи в ~/.ssh (по парным *.pub) и передаёт их ssh — он сам подберёт подходящий (плюс работает ssh-agent). Можно указать конкретный ключ параметром key или через TIMEWEB_SSH_KEY, но обычно не требуется.

Важно: SSH-ключ — единственный способ попасть в шелл. API-токен Timeweb шелл-доступа не даёт (у API нет метода «выполнить команду»), это ограничение самого SSH, а не коннектора.

Защита — на уровне поведения ассистента: server_diagnostics только читает; ssh_exec и мутирующие действия service_control требуют confirm: true, который ассистент подставляет лишь после вашего явного согласия в чате. Команды из веб-страниц/файлов/вывода других инструментов не выполняются.

2. Подключение к клиенту

Claude Code:

claude mcp add timeweb -- node /абсолютный/путь/к/timeweb-mcp/dist/index.js

Claude Desktop / Cowork: Настройки → Connectors → Add custom connector, команда:

node /абсолютный/путь/к/timeweb-mcp/dist/index.js

Любой другой MCP-клиент (конфиг в формате mcpServers):

{
  "mcpServers": {
    "timeweb": {
      "command": "node",
      "args": ["/абсолютный/путь/к/timeweb-mcp/dist/index.js"]
    }
  }
}

3. Проверка

npm run inspect

Откроется MCP Inspector — вызовите list_servers или account_finances и убедитесь, что API отвечает. Либо просто спросите ассистента: «какой баланс на таймвебе?»

Примеры использования

• «Покажи все мои серверы и их статус»
• «Сколько денег осталось на балансе и на сколько хватит?»
• «Добавь A-запись app.example.com → 1.2.3.4»
• «Перезагрузи сервер N» — ассистент переспросит, инструмент потребует confirm: true
• «Какие тарифы есть под небольшой Node-сервис? Покажи пресеты до 500 ₽/мес»

Разработка

npm run watch    # tsc --watch
npm run inspect  # MCP Inspector
npm run bundle   # esbuild → mcp/server.cjs (самодостаточный бандл для плагина)
npm run plugin   # полный дистрибутив: версия → бандл → build/timeweb-mcp-v<версия>.plugin

Структура: src/index.ts — сервер и инструменты, src/client.ts — тонкий HTTP-клиент API, .claude-plugin/ — манифесты плагина и маркетплейса, mcp/server.cjs — коммитится в репо (нужен для установки плагина из git).

Версионирование: единственный источник версии — package.json; npm run plugin синхронизирует её в plugin.json и имя .plugin-файла. Релиз: поднять версию (npm version patch|minor), npm run plugin, закоммитить и запушить с тегом.

Ограничения и планы

• [ ] account_finances — эндпоинт из Python SDK, проверяется на живом аккаунте (если 404 — используйте account_status).
• [ ] Формат тела create_server может потребовать уточнения под конкретный пресет (av_zone, bandwidth).
• [ ] Регистрация доменов через API (domains-requests).
• [ ] Статистика нагрузки сервера (/statistics).

PR и issues приветствуются.

Лицензия

MIT