sqlite-readonly-mcp

Сервер SQLite в режиме только для чтения для протокола Model Context Protocol, работающий на удаленном сервере Linux. Использует Streamable HTTP (/mcp), аутентификацию через Bearer Token, а результаты запросов возвращаются в виде JSON-текста. Разработан для размещения за Nginx (HTTPS), при этом вышестоящий сервер прослушивает только локальный хост.

Функции

• Инструмент sqlite_query: выполнение одиночного запроса SELECT / WITH / EXPLAIN, возвращает JSON в формате { rows, rowCount }.

• Инструмент list_tables: вывод списка имен таблиц (за исключением системных).

• SQLite: better-sqlite3 с флагами readonly + fileMustExist; на уровне приложения ограничено выполнение только одного оператора и проверка префикса запроса.

• GET /health: только для локального доступа, используется для проверки работоспособности (см. src/server.ts).

• Передача данных: Streamable HTTP (/mcp) + устаревший SSE (GET /sse, POST /messages) для обеспечения обратной совместимости с Cursor при необходимости.

Related MCP server: PostgreSQL MCP Server

Переменные окружения

Локальная сборка и запуск

npm install
npm run build
export SQLITE_PATH=/path/to/db.sqlite
export BEARER_TOKEN='your-secret-token'
export ALLOWED_HOSTS='127.0.0.1,localhost'
node dist/server.js

Разработка и отладка: npm run dev

Nginx и systemd

См. deploy/nginx.example.conf, deploy/sqlite-readonly-mcp.service, deploy/sqlite-readonly-mcp.env.example.

Основные моменты: передача заголовков Authorization, Accept, Content-Type, mcp-session-id на вышестоящий сервер; отключение proxy_buffering для SSE/потоковых ответов. В примерах уже включены **/sse**, **/messages** (устаревший SSE-откат) вместе с Streamable HTTP /mcp для обратного проксирования.

Запуск от имени пользователя root (рекомендуемый пример)

Для упрощения настройки прав доступа на чтение к файлу SQLite и родительскому каталогу, в примере сервис запускается от имени root (в unit-файле systemd не указаны User= / Group=, по умолчанию используется root).

1. Разместите код и артефакты сборки, например, в /opt/sqlite-readonly-mcp, и выполните npm ci --omit=dev и npm run build.

2. Скопируйте файл окружения и заполните переменные:

 sudo cp deploy/sqlite-readonly-mcp.env.example /etc/sqlite-readonly-mcp.env
 sudo chmod 600 /etc/sqlite-readonly-mcp.env

3. Установите и активируйте unit-файл (при необходимости измените WorkingDirectory и абсолютный путь к node в ExecStart):

 sudo cp deploy/sqlite-readonly-mcp.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable --now sqlite-readonly-mcp
 sudo systemctl status sqlite-readonly-mcp

Если вы ранее добавляли User=mcp, удалите эту строку, затем выполните daemon-reload и restart.

Совет по безопасности: взлом процесса root несет более серьезные последствия, поэтому обязательно используйте HTTPS, Bearer-токены, прослушивание локального хоста + Nginx, брандмауэр; если требуются минимальные привилегии, вернитесь к использованию выделенного пользователя и настройте права доступа к файлу данных и путям отдельно.

Ручная проверка (curl)

MCP требует, чтобы клиент принимал как application/json, так и text/event-stream:

curl -sS -D - \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  "https://mcp.example.com/mcp"

Неверный токен должен возвращать 401.

Клиент Cursor

В настройках MCP в Cursor укажите HTTPS URL для этого удаленного сервиса (например, https://mcp.example.com/mcp). Если требуется Bearer-токен, проверьте, поддерживает ли текущая версия Cursor настройку пользовательских заголовков для удаленных MCP; если нет, потребуется добавить локальный шлюз с фиксированным заголовком Authorization (см. описание рисков решения).

Эксплуатация

Подробности см. в docs/RUNBOOK.md.

Лицензия

MIT (в соответствии с @modelcontextprotocol/sdk; действуют лицензии соответствующих зависимостей).