Oracle Database MCP Server

Сервер протокола Model Context Protocol (MCP), который позволяет GitHub Copilot и другим LLM выполнять SQL-запросы только для чтения к базам данных Oracle.

Содержание

1. Настройка macOS (Apple Silicon — M1/M2/M3/M4)

2. Установка

3. Настройка VS Code

4. Опционально: создание пользователя с правами только для чтения

5. Возможности

6. Доступные инструменты

7. Справочник конфигурации

8. Разработка

9. Вопросы безопасности

10. Устранение неполадок

11. Документация

12. Лицензирование

Related MCP server: MCP Server for Oracle Database

🍎 Настройка macOS (Apple Silicon — M1/M2/M3/M4)

Это рекомендуемый путь для пользователей Mac. Мы используем Colima в качестве среды выполнения Docker (она легче, чем Docker Desktop, и работает нативно на Apple Silicon) и собираем MCP-сервер из исходного кода.

Шаг 1 — Установка необходимых компонентов

Homebrew (пропустите, если уже установлено):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Node.js v18+ через nvm (рекомендуется):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload your shell config, then install Node
source ~/.zshrc
nvm install 20
nvm use 20
node --version    # should print v20.x.x

Или через Homebrew:

brew install node
node --version

Colima + Docker CLI:

brew install colima docker

Шаг 2 — Запуск Colima

Colima — это легковесная среда выполнения контейнеров для macOS — Docker Desktop не требуется.

# Start with enough resources for Oracle XE (needs at least 2GB RAM)
colima start --cpu 2 --memory 4 --disk 30

# Verify Docker is working
docker ps

Если у вас уже запущен Colima с меньшим объемом памяти, выполните colima stop, а затем перезапустите с указанными выше флагами.

Шаг 3 — Загрузка и запуск Oracle XE

Реестр контейнеров Oracle требует наличия бесплатной учетной записи для загрузки образа.

1. Создайте бесплатную учетную запись на https://container-registry.oracle.com

2. Войдите в систему, перейдите в Database → express и нажмите Accept License Agreement

3. Войдите в систему через терминал:

docker login container-registry.oracle.com
# Enter your Oracle account email and password when prompted

4. Загрузите и запустите Oracle XE 21c:

docker run -d \
  --name oracle-xe \
  -p 1521:1521 \
  -p 5500:5500 \
  -e ORACLE_PWD=OraclePwd123 \
  container-registry.oracle.com/database/express:latest

5. Дождитесь готовности (при первом запуске занимает 60–90 секунд):

# Poll health status — wait for "healthy"
watch -n 5 'docker inspect --format="{{.State.Health.Status}}" oracle-xe'

# Or tail the logs directly
docker logs -f oracle-xe
# Look for: DATABASE IS READY TO USE!

Ваша база данных теперь доступна по адресу:

• Строка подключения: localhost:1521/XE

• Пароль SYSTEM: OraclePwd123

• Веб-интерфейс (EM Express): http://localhost:5500/em

Примечание об имени службы: Oracle XE 21c имеет два имени службы:

• XE — база данных контейнера (CDB), используется с пользователем SYSTEM

• XEPDB1 — подключаемая база данных (PDB), используется для обычных пользователей приложения

Чтобы запустить или остановить базу данных позже:

docker start oracle-xe
docker stop oracle-xe

Шаг 4 — Клонирование и сборка MCP-сервера

git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build

Шаг 5 — Настройка окружения

cp .env.example .env

Отредактируйте .env для локальной Oracle XE (подходит для тестирования):

ORACLE_CONNECTION_STRING=localhost:1521/XE
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123

Для использования в продакшене сначала создайте выделенного пользователя с правами только для чтения — см. Создание пользователя с правами только для чтения.

Шаг 6 — Тестирование сервера

# Core tests: connects to Oracle, queries schema and version
npm run test-client

# Schema discovery tool tests
npm run test-discovery

Ожидаемый вывод:

✅ All tests completed successfully!

📊 Test Summary:
1. List Tools: ✅
2. List Tables (fast): ✅
3. List Tables (with counts): ✅
4. Describe Table: ✅
5. Get Table Relations: ✅
6. Get Sample Values: ✅
7. Suggest Related Tables: ✅
8. Cache Test: ✅

Шаг 7 — Подключение VS Code

См. Настройка VS Code ниже.

📦 Установка

Сборка из исходного кода (рекомендуется)

Предоставляет актуальный код и позволяет запустить набор тестов для проверки работоспособности перед подключением к Copilot.

git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build

Установка из npm

Если вам нужен только бинарный файл сервера без клонирования исходного кода:

npm install -g mcp-oracle-database

🔌 Настройка VS Code

Вариант А — Из исходного кода (рекомендуется)

Создайте .vscode/mcp.json в вашей рабочей области VS Code (или добавьте в глобальную конфигурацию MCP):

{
  "servers": {
    "oracleDatabase": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-oracle-database/dist/server.js"],
      "env": {
        "ORACLE_CONNECTION_STRING": "localhost:1521/XE",
        "ORACLE_USER": "system",
        "ORACLE_PASSWORD": "OraclePwd123",
        "ORACLE_POOL_MIN": "2",
        "ORACLE_POOL_MAX": "10",
        "QUERY_TIMEOUT_MS": "30000",
        "MAX_ROWS_PER_QUERY": "1000",
        "ENFORCE_READ_ONLY_QUERIES": "true",
        "MCP_MAX_RESPONSE_CHARS": "50000",
        "MCP_MAX_ROWS_IN_RESPONSE": "200",
        "MCP_MAX_STRING_LENGTH": "500"
      }
    }
  }
}

Замените /absolute/path/to/mcp-oracle-database на реальный путь на вашем компьютере (например, /Users/yourname/GITHUB/mcp-oracle-database).

Вариант Б — Из глобальной установки npm

{
  "servers": {
    "oracleDatabase": {
      "type": "stdio",
      "command": "mcp-database-server",
      "env": {
        "ORACLE_CONNECTION_STRING": "localhost:1521/XE",
        "ORACLE_USER": "your_user",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_POOL_MIN": "2",
        "ORACLE_POOL_MAX": "10",
        "QUERY_TIMEOUT_MS": "30000",
        "MAX_ROWS_PER_QUERY": "1000",
        "ENFORCE_READ_ONLY_QUERIES": "true",
        "MCP_MAX_RESPONSE_CHARS": "50000",
        "MCP_MAX_ROWS_IN_RESPONSE": "200",
        "MCP_MAX_STRING_LENGTH": "500"
      }
    }
  }
}

После сохранения конфигурации перезагрузите VS Code и откройте чат Copilot в режиме агента (Agent mode). Попробуйте:

"What tables are in the database?"
"Describe the HELP table"
"Show me 5 rows from the HELP table"

Опционально: создание пользователя с правами только для чтения

Использование SYSTEM подходит для локального тестирования, но для любой реальной базы данных создайте выделенного пользователя с правами только для чтения.

Подключитесь к Oracle (например, через sqlplus или GUI, такой как DBeaver):

-- For Oracle XE local Docker, connect with:
-- sqlplus system/OraclePwd123@localhost:1521/XEPDB1

CREATE USER readonly_user IDENTIFIED BY secure_password;
GRANT CREATE SESSION TO readonly_user;
GRANT SELECT ANY TABLE TO readonly_user;

-- Or restrict to specific tables:
-- GRANT SELECT ON myschema.orders TO readonly_user;
-- GRANT SELECT ON myschema.customers TO readonly_user;

Затем обновите ваш .env или конфигурацию MCP:

ORACLE_CONNECTION_STRING=localhost:1521/XEPDB1
ORACLE_USER=readonly_user
ORACLE_PASSWORD=secure_password

Возможности

• 🔒 Доступ только для чтения — использует выделенного пользователя БД с правами только для чтения для безопасности

• 📡 Транспорт stdio — обмен данными через стандартный ввод/вывод (HTTP-сервер не требуется)

• ⚡ Пул соединений — эффективное управление соединениями Oracle

• 📊 Интроспекция схемы — запрос информации о таблицах и столбцах

• 🔍 Расширенное обнаружение схемы — 5 специализированных инструментов для поиска таблиц, связей и шаблонов данных

• 💾 Кэширование в памяти — быстрый повторный доступ с LRU-кэшем (TTL 5 минут)

• 📝 Аудит-логирование — все запросы логируются с метриками выполнения

• ⏱️ Защита по тайм-ауту — предотвращает выполнение длительных запросов

• 🛡️ Ограничение результатов — настраиваемые лимиты строк для предотвращения проблем с памятью

• 🍎 Oracle Client не требуется — использует node-oracledb в режиме Thin Mode (чистый JS, работает на Apple Silicon)

Архитектура

GitHub Copilot / LLM
        ↓ (MCP Protocol)
  MCP Client (spawns process)
        ↓ (JSON-RPC over stdio)
    MCP Server (Node.js)
        ↓ (node-oracledb Thin Mode)
  Oracle Database (read-only user)

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

Основные инструменты

query_database

Выполнение SQL-запросов SELECT только для чтения.

{
  "query": "SELECT table_name FROM user_tables FETCH FIRST 10 ROWS ONLY",
  "maxRows": 10
}

get_database_schema

Получение списка таблиц или подробной информации о столбцах для конкретной таблицы.

{ "tableName": "ORDERS" }

Инструменты обнаружения схемы

Пять специализированных инструментов для комплексной интроспекции схемы:

📖 См. Документацию по обнаружению схемы для получения подробной информации и примеров.

Примеры промптов для Copilot

"List all tables in the database"
"Describe the ORDERS table and its relationships"
"How many active users are there?"
"What are the top 5 products by sales this month?"
"Show me recent transactions for customer ID 12345"

Справочник конфигурации

Все настройки можно указать в .env или в качестве ключей env в вашей конфигурации MCP для VS Code.

# Oracle Database Connection
ORACLE_CONNECTION_STRING=localhost:1521/XE    # host:port/service
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123

# Connection Pool
ORACLE_POOL_MIN=2
ORACLE_POOL_MAX=10

# Query Safety
QUERY_TIMEOUT_MS=30000           # max query time in ms
MAX_ROWS_PER_QUERY=1000          # max rows Oracle will fetch
MAX_QUERY_LENGTH=50000           # max SQL length in chars
ENFORCE_READ_ONLY_QUERIES=true   # reject non-SELECT statements

# MCP Response Limits
MCP_MAX_RESPONSE_CHARS=50000     # hard cap on total response size
MCP_MAX_ROWS_IN_RESPONSE=200     # max rows per tool call response
MCP_MAX_STRING_LENGTH=500        # max chars per string field

# Logging
LOG_LEVEL=info
ENABLE_AUDIT_LOGGING=true
ENABLE_FILE_LOGGING=true
LOG_DIR=./logs
NODE_ENV=development

Большие схемы: Если в вашей базе данных более 500 таблиц, увеличьте MCP_MAX_RESPONSE_CHARS до 100000.

Разработка

Скрипты

npm run build          # Compile TypeScript → dist/
npm run dev            # Watch mode compilation
npm run clean          # Remove dist/
npm run typecheck      # Type-check without compiling
npm start              # Start MCP server (requires build first)
npm run test-client    # Core tool tests against live Oracle DB
npm run test-discovery # Schema discovery tool tests

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

mcp-oracle-database/
├── src/
│   ├── server.ts               # MCP server entry point
│   ├── client.ts               # Core test client
│   ├── test-discovery.ts       # Discovery tools test client
│   ├── config.ts               # Zod-validated configuration
│   ├── database/
│   │   ├── oracleConnection.ts # Connection pool manager
│   │   ├── queryExecutor.ts    # Query execution + safety checks
│   │   └── types.ts
│   ├── tools/
│   │   ├── queryDatabase.ts    # query_database tool
│   │   ├── getSchema.ts        # get_database_schema tool
│   │   └── discovery/          # 5 schema discovery tools + cache
│   └── utils/
│       ├── logger.ts           # Lightweight file + console logger
│       └── responseFormatter.ts # MCP response size management
├── dist/                       # Compiled output (git-ignored)
├── .env                        # Your credentials (git-ignored)
├── .env.example                # Template
└── package.json

Вопросы безопасности

1. Пользователь только для чтения — в продакшене пользователь БД должен иметь только права SELECT

2. Отсутствие защиты от инъекций — сервер доверяет LLM генерацию корректного SQL; пользователь с правами только для чтения является защитным барьером

3. Ограничения запросов — лимиты на количество строк и тайм-ауты предотвращают исчерпание ресурсов

4. Аудит-логирование — все запросы логируются с метками времени для проверки

5. Локальное использование — этот сервер предназначен для запуска прямо на вашем компьютере; он может работать локально и при этом получать доступ к удаленным базам данных.

Устранение неполадок

Colima не запущена (macOS)

colima status
colima start --cpu 2 --memory 4   # Oracle needs at least 2GB RAM
docker ps                          # verify Docker is available

Проблемы с контейнером Oracle

# Check if container exists
docker ps -a | grep oracle-xe

# View startup logs
docker logs oracle-xe

# Already exists but stopped — just start it
docker start oracle-xe

# Check health status
docker inspect --format='{{.State.Health.Status}}' oracle-xe
# Wait for: healthy

Ошибка подключения

Error: ORA-12545: Connect failed because target host or object does not exist

• Запущен ли Oracle? docker ps | grep oracle-xe

• Проверьте проброс портов: docker ps должен показывать 0.0.0.0:1521->1521/tcp

• Попробуйте localhost:1521/XE для пользователя SYSTEM, localhost:1521/XEPDB1 для других пользователей

Неверное имя службы

Отказано в доступе (Permission denied)

Error: ORA-00942: table or view does not exist

Предоставьте права SELECT вашему пользователю:

GRANT SELECT ANY TABLE TO your_user;

Требуется вход в реестр контейнеров Oracle

Error: unauthorized: authentication required

1. Создайте бесплатную учетную запись на https://container-registry.oracle.com

2. Примите лицензию для Database → express

3. Выполните docker login container-registry.oracle.com

Ответ слишком большой

Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS

Увеличьте лимит в .env или в конфигурации MCP VS Code:

MCP_MAX_RESPONSE_CHARS=100000

Примечание о Thin Mode

Этот проект использует Thin Mode для node-oracledb — драйвер на чистом JavaScript, который не требует Oracle Instant Client. Он работает на всех платформах, включая Mac на Apple Silicon.

Документация

📚 Руководства по интеграции:

• Руководство по обнаружению схемы — инструменты расширенной интроспекции схемы

• Краткий справочник по обнаружению схемы — шпаргалка по всем инструментам обнаружения

• Примеры обнаружения схемы — примеры сообщений MCP

• Руководство по интеграции с VS Code — настройка с GitHub Copilot

• Руководство по интеграции с Claude Desktop — настройка с Claude Desktop

• Руководство по интеграции MCP — глубокое погружение в протокол MCP

• Обзор архитектуры — диаграмма архитектуры системы

• Настройка логирования — настройка и конфигурация логирования

📝 Пользовательские инструкции:

• .github/copilot-instructions.md — инструкции для Copilot по всему проекту

• .github/instructions/ — рекомендации по написанию кода для конкретных языков

Oracle является зарегистрированным товарным знаком Oracle Corporation. Этот проект не связан, не одобрен и не спонсируется Oracle Corporation.

Лицензирование

Этот проект доступен под лицензией GNU General Public License v3.0 (GPLv3).

🟢 Open Source — GPLv3

Если вы выбираете GPLv3, вы получаете права GPLv3 в том виде, в котором они написаны, без дополнительных ограничений на использование. См. LICENSE для полного текста лицензии и LICENSE.md для краткого обзора лицензирования.

🔵 Коммерческая и государственная — Платная лицензия

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

📄 См. LICENSE.md для обзора лицензирования. 📄 См. COMMERCIAL_LICENSE.md для условий отдельной коммерческой/государственной лицензии.

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

Вклад приветствуется! Пожалуйста, откройте issue или pull request.