Timeweb Cloud MCP Server

MCP-сервер для управления инфраструктурой Timeweb Cloud из Cursor, VS Code и других клиентов, поддерживающих Model Context Protocol.

Сервер работает через stdio, принимает вызовы MCP-инструментов и выполняет соответствующие запросы к API Timeweb Cloud.

Возможности

Текущая сборка регистрирует:

Инструменты охватывают основные операции со следующими сервисами:

• приложения App Platform и VCS-провайдеры;

• облачные и выделенные серверы, диски, резервные копии и образы;

• проекты, VPC, плавающие IP, сетевые диски и Firewall;

• Kubernetes, балансировщики и реестры контейнеров;

• базы данных;

• S3-хранилища;

• домены, DNS и почта;

• SSH-ключи и API-ключи;

• AI-агенты;

• аккаунт, платежная информация, тарифы и локации.

Доступные MCP-ресурсы:

• allowed_presets;

• vcs_providers;

• vcs_provider_repositories;

• deploy_settings;

• database_presets;

• get_vpcs.

Доступные промпты:

• create_app_prompt;

• add_vcs_provider_prompt.

Полный список фактически зарегистрированных инструментов находится в src/tools/index.ts.

Related MCP server: Dokploy MCP Server

Требования

• Node.js 20 или новее;

• npm;

• MCP-клиент с поддержкой локальных stdio-серверов;

• API-токен Timeweb Cloud.

Получение API-токена

Создайте токен в панели Timeweb Cloud в разделе «API и Terraform». Официальная инструкция: Токены API и Terraform.

Проект ожидает токен в переменной окружения:

TIMEWEB_TOKEN

Не путайте её с TIMEWEB_CLOUD_TOKEN, которая используется в некоторых других инструментах Timeweb Cloud.

По возможности выпускайте токен с ограниченными правами и сроком действия. Не сохраняйте настоящий токен в Git.

Быстрый старт

Пакет не требует глобальной установки:

npx -y timeweb-mcp

Обычно сервер запускает MCP-клиент, передавая TIMEWEB_TOKEN через свою конфигурацию.

Подключение MCP-клиента

Cursor

Добавьте сервер в .cursor/mcp.json:

{
  "mcpServers": {
    "timeweb-cloud": {
      "command": "npx",
      "args": ["-y", "timeweb-mcp"],
      "env": {
        "TIMEWEB_TOKEN": "your-timeweb-token"
      }
    }
  }
}

Не добавляйте конфигурацию с настоящим токеном в публичный репозиторий.

VS Code

VS Code хранит конфигурацию рабочего пространства в .vscode/mcp.json. Токен можно запрашивать через защищённое поле ввода:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "timeweb-token",
      "description": "Timeweb Cloud API token",
      "password": true
    }
  ],
  "servers": {
    "timeweb-cloud": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "timeweb-mcp"],
      "env": {
        "TIMEWEB_TOKEN": "${input:timeweb-token}"
      }
    }
  }
}

Управлять сервером можно через команды MCP: List Servers и MCP: Open Workspace Folder MCP Configuration.

Другие MCP-клиенты

Для клиентов, использующих формат mcpServers, базовая конфигурация выглядит так:

{
  "mcpServers": {
    "timeweb-cloud": {
      "command": "npx",
      "args": ["-y", "timeweb-mcp"],
      "env": {
        "TIMEWEB_TOKEN": "your-timeweb-token"
      }
    }
  }
}

Название корневого поля и способ безопасного хранения секретов зависят от конкретного MCP-клиента.

Локальная разработка

Клонируйте репозиторий и установите зависимости:

git clone https://github.com/ichinya/timeweb-mcp.git
cd timeweb-mcp
npm ci

Создайте локальный файл .env:

TIMEWEB_TOKEN=your-timeweb-token

Проверьте типы и соберите сервер:

npm run type-check
npm run build

Запустите локальную сборку:

npm run start

MCP Inspector

MCP Inspector позволяет просматривать инструменты, ресурсы и промпты, а также выполнять тестовые вызовы:

npm run inspect

Перед запуском добавьте TIMEWEB_TOKEN в .env.

Команды разработки

Выпуск новой версии

Пакет публикуется автоматически из GitHub Actions через npm Trusted Publishing. Постоянный NPM_TOKEN в репозитории не используется.

1. Обновите версию одновременно в package.json и package-lock.json:

   npm version patch --no-git-tag-version

   Вместо patch можно использовать minor, major или указать точную версию.

2. Закоммитьте и отправьте изменения в main.

3. Workflow .github/workflows/publish.yml сравнит новую версию с версией предыдущего коммита.

4. Если версия увеличилась, workflow проверит проект, создаст тег vX.Y.Z, опубликует пакет с той же версией в npm и создаст GitHub Release.

Создавать тег или GitHub Release вручную не нужно. Изменение других полей package.json без повышения версии не запускает выпуск. Понижение версии считается ошибкой.

Trusted Publisher в настройках npm должен быть связан со следующими значениями:

• GitHub user: ichinya;

• repository: timeweb-mcp;

• workflow filename: publish.yml;

• allowed action: npm publish;

• environment: не задан.

Публикация выполняется на GitHub-hosted runner через OIDC и автоматически получает npm provenance.

OpenAPI-спецификация

Официальные источники:

• интерактивная документация API;

• OpenAPI JSON.

Локальная копия находится в specs/openapi.json.

Текущая спецификация содержит:

• OpenAPI 3.0.0;

• 212 путей;

• 341 операцию;

• 23 группы;

• 283 схемы компонентов.

Обновление спецификации

PowerShell:

Invoke-WebRequest `
  -Uri "https://timeweb.cloud/api-docs-data/bundle.json" `
  -OutFile "specs/openapi.json"

npm run normalize:openapi
npm run validate:openapi

macOS или Linux:

curl -fsSL \
  https://timeweb.cloud/api-docs-data/bundle.json \
  -o specs/openapi.json

npm run normalize:openapi
npm run validate:openapi

Нормализация переименовывает только конфликтующие ключи в components.schemas и соответствующие внутренние $ref:

Это устраняет коллизии имён файлов и TypeScript-моделей на файловых системах без учёта регистра. Названия полей запросов и ответов, пути API и wire-формат данных не изменяются.

Скрипт проверки контролирует:

• версию OpenAPI;

• наличие и уникальность operationId;

• разрешение внутренних $ref;

• отсутствие коллизий генерируемых TypeScript-имён моделей.

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

src/
  actions/      вызовы API и прикладные операции
  api/          клиенты сервисов Timeweb Cloud
  prompts/      MCP-промпты
  resources/    MCP-ресурсы
  tools/        определения и схемы MCP-инструментов
  types/        типы и DTO
scripts/
  normalize-openapi.mjs
  validate-openapi.mjs
specs/
  openapi.json

API-клиенты в src/api поддерживаются вручную. Код сервера пока не генерируется автоматически из specs/openapi.json.

Безопасность

Инструменты выполняют операции над реальной инфраструктурой и могут создавать платные ресурсы, менять конфигурацию или удалять данные.

• Проверяйте имя инструмента и все аргументы перед подтверждением вызова.

• Используйте отдельный API-токен с минимально необходимыми правами.

• Не передавайте токен в сообщения модели и не сохраняйте его в Git.

• Сначала проверяйте опасные сценарии на тестовых ресурсах.

• Не полагайтесь только на MCP-аннотации: сейчас инструменты регистрируются с одинаковыми подсказками и не всегда корректно обозначают операции удаления или изменения данных.

Локальные MCP-серверы выполняются на машине пользователя с правами запустившего их процесса. Подключайте только доверенный код и проверяйте изменения перед обновлением.

Известные ограничения

• Проект находится в экспериментальном состоянии.

• MCP-покрытие не равно полному покрытию официальной OpenAPI-спецификации.

• API-клиенты и DTO поддерживаются вручную и могут отставать от API.

• Автоматические тесты и отдельный CI-workflow пока не настроены; GitHub Actions используется только для публикации релизов в npm.

Ссылки

• Репозиторий: ichinya/timeweb-mcp

• npm: timeweb-mcp

• Официальная документация Timeweb Cloud: timeweb.cloud/docs

• Официальная документация API: timeweb.cloud/api-docs

Лицензия

В package.json указано UNLICENSED, отдельный файл лицензии отсутствует. Не предполагайте разрешение на распространение или повторное лицензирование кода без согласования с правообладателем.