SQLPad MCP Server

MCP сервер для SQLPad. Укажите ИИ-агенту базовый URL экземпляра SQLPad и сервисный токен — и агент сможет обнаруживать подключения, просматривать схемы, выполнять SQL и управлять сохранёнными запросами.

Требования

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

• Доступный экземпляр SQLPad.

• На сервере SQLPad должен быть настроен SQLPAD_SERVICE_TOKEN_SECRET. Без него каждый запрос с Bearer-аутентификацией возвращает 401 Unauthorized.

• Сервисный токен, созданный в административном интерфейсе SQLPad.

Related MCP server: SQLite Database MCP Server

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

Установка не требуется — запускайте прямо из npm:

SQLPAD_SERVICE_TOKEN=... npx sqlpad-mcp --base-url https://sqlpad.example.com

Или установите глобально:

npm install -g sqlpad-mcp

Сервер общается по MCP через stdio, поэтому обычно его запускает MCP-клиент, а не вручную. Однако прямой запуск полезен для проверки учётных данных: при успехе он выводит обнаруженную версию SQLPad в stderr.

Конфигурация

Флаг CLI имеет приоритет над соответствующей переменной окружения. Интервал опроса пакета (250 мс) является внутренним и не настраивается.

Конфигурация Claude Code

Добавьте сервер в ваш mcp.json для Claude Code:

{
  "mcpServers": {
    "sqlpad": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "sqlpad-mcp",
        "--base-url",
        "https://sqlpad.example.com"
      ],
      "env": {
        "SQLPAD_SERVICE_TOKEN": "..."
      }
    }
  }
}

Передача токена через env не позволяет ему попасть в список аргументов процесса, который доступен для чтения всем через ps.

Чтобы включить группы инструментов, управляемые флагами, добавьте "SQLPAD_ALLOW_WRITES": "true" или "SQLPAD_ALLOW_ADMIN": "true" в тот же блок env.

Инструменты

Двенадцать инструментов регистрируются всегда. Ещё шесть скрыты за двумя флагами SQLPAD_ALLOW_* и по умолчанию отключены.

Выполнение

Обнаружение

Сохранённые запросы

Запись сохранённых запросов — требует SQLPAD_ALLOW_WRITES=true

Администрирование — требует SQLPAD_ALLOW_ADMIN=true

Эти инструменты вызывают конечные точки SQLPad, которые сами требуют сервисный токен администратора.

Как работает выполнение SQL

SQLPad выполняет SQL через асинхронные пакеты. Создание пакета возвращается немедленно; каждый оператор переходит из состояния queued в started, затем в finished или error. Результаты извлекаются отдельно для каждого оператора и недоступны, пока оператор не завершён.

Инструмент run_sql поглощает весь протокол — создание, опрос, извлечение и возврат строк — так что агенту достаточно одного вызова. Если опрос достигает настроенного тайм-аута, инструмент возвращает batchId, который агент может использовать для возобновления, вместо зависания.

У подключений может не быть базы данных по умолчанию. Квалифицируйте имена таблиц как schema.table и используйте get_connection_schema для обнаружения доступных схем.

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

• run_sql выполняет произвольный SQL, включая DDL и DML, и не изолирован в песочнице. SQLPAD_ALLOW_WRITES ограничивает только изменение собственных сохранённых запросов SQLPad; он не ограничивает содержимое SQL. Используйте учётные данные базы данных только для чтения на самом подключении SQLPad. Это единственное реальное ограничение.

• Конечные точки SQLPad /api/service-tokens намеренно не раскрываются. Инструмент, создающий учётные данные, является примитивом повышения привилегий.

• Административные инструменты по умолчанию отключены.

• Сервисный токен скрывается из всех ошибок и журналов. Все журналы идут в stderr, потому что stdout — это канал JSON-RPC.

• Пакеты ограничены пользователем самого токена, поэтому сервер видит только свою собственную историю запросов.

Участие в разработке

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

git clone https://github.com/VAIBHAV7500/sqlpad-mcp.git
cd sqlpad-mcp
npm install
npm run build

Создайте ветку для вашего изменения. Перед открытием pull request выполните:

npm run typecheck && npm run lint && npm test

CI запускает те же три команды на Node 20 и 22.

Лицензия

MIT