MCP-Oracle

Испанский | Английский

MCP (Model Context Protocol) — сервер, подключающий ИИ-агента к базе данных Oracle.

Он предоставляет инструменты для изучения схемы, чтения исходного кода PL/SQL и выполнения SQL. Он запускается в режиме только для чтения; запись и вызовы хранимых процедур включаются с помощью ORACLE_ALLOW_WRITE=true.

Он использует официальный Python SDK (mcp) и python-oracledb. Если найден Instant Client (или каталог lib/ внутри ORACLE_HOME), включается толстый режим; в противном случае используется тонкий режим. Толстый режим обязателен для более старых экземпляров (10g/11g), чей верификатор пароля не поддерживается в тонком режиме.

Этот проект — не официальный набор Oracle MCP (oracle/mcp). Этот репозиторий посвящён Oracle Cloud и другим продуктам Oracle. Этот сервер обращается напрямую к вашему экземпляру базы данных.

Инструменты

run_query и execute_dml принимают связываемые переменные (:name), чтобы вам не приходилось вставлять значения прямо в SQL.

Related MCP server: Oracle DB MCP Server

Требования

• Python 3.9+

• Доступ к экземпляру Oracle (пользователь, пароль, хост, порт и service_name)

• Для Oracle 10g/11g (или когда тонкий режим не работает): Oracle Instant Client или каталог lib/ внутри ORACLE_HOME

Локальное использование и продакшн

Этот README описывает локальное использование: Cursor или Claude Desktop запускают server.py на вашей машине через stdio (HTTP-порт не открывается).

Если MCP должен постоянно работать на сервере, а клиенты подключаются по сети:

• Linux (RedHat)

• Windows Server

Установка

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Скопируйте шаблон переменных окружения и заполните его своими значениями:

cp .env.example .env

Сервер не загружает .env автоматически. Эти переменные должны быть переданы в конфигурацию MCP-клиента (Cursor, Claude Desktop и т. д.). Файл .env — это локальный справочник; не добавляйте его в коммит.

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

Толстый и тонкий режим

При запуске сервер проверяет ORACLE_CLIENT_LIB_DIR (или ~/oracle/instantclient). Если эта папка существует, вызывается oracledb.init_oracle_client() и используется толстый режим.

Примеры:

# Instant Client (zip / RPM)
ORACLE_CLIENT_LIB_DIR=/Users/your_user/oracle/instantclient

# ORACLE_HOME 19c
ORACLE_CLIENT_LIB_DIR=/apps/oracle/product/19c/lib

Если нативного клиента нет, сервер работает в тонком режиме (обычно Oracle 12.1+).

Использование с Cursor

В Cursor добавьте сервер в конфигурацию MCP (например, ~/.cursor/mcp.json or инстру project configuration):

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Используйте абсолютный путь к Python из .venv, чтобы клиент нашёл модули mcp и oracledb.

Перезапустите Cursor (или перезагрузите MCP-серверы) и убедитесь, что oracle-mcp появился в списке инструментов.

Использование с Claude Desktop

В claude_desktop_config.json:

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Запуск вручную

Локально сервер общается через MCP по STDIO stdio (он не открывает HTTP-порт). На продакшн-сервере используется HTTP-транспорт; подробнее см. Локальное использование и продакшн.

source .venv/bin/activate
export ORACLE_USER=my_user
export ORACLE_PASSWORD=my_password
export ORACLE_HOST=127.0.0.1
export ORACLE_PORT=1521
export ORACLE_SERVICE_NAME=ORCLPDB1
python server.py

Без подключённого MCP-клиента к stdin/stdout интерактивного приглашения не будет; это ожидаемое поведение.

Security

• По умолчанию ORACLE_ALLOW_WRITE=false: execute_dml и call_procedure завершаются с PermissionError.

• run_query отклоняет запросы, начинающиеся с INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, TRUNCATE, CREATE, GRANT или REVOKE.

• execute_dml принимает только INSERT, UPDATE, DELETE или MERGE.

• Предпочитайте связываемые переменные (:id) instead of inserting values directly into SQL. Instead of конкатенации значений в SQL используйте связываемые переменные (:id).

• Подключайтесь с пользователем "least privilege", если нужно только взаимодействовать со схемой.

• Не добавляйте в коммит .env или учетные данные в версионируемом mcp.json.

Зависимости

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0

Wait "Security" should be "##Security" in translation? I accidentally wrote "## Security". Need fix: "## Безопасность". Also the bullet about bind variables: I accidentally have English sentence. Need fix to Russian: "Предпочитайте связываемые переменные (:id) вместо конкатенации значений в SQL." Let's fix.

Also "проек config" in Cursor section: I wrote "or the project configuration" accidentally mixed. Need "или его проекта" or "или настройками проекта". We'll rewrite.

Need sanity: bullet "Добавляйте пользователя с минимальными привилегиями": Let's fix.

Need "Local use and production" anchor has original #local-use-vs-production keep.

Need "ORA service names" row "ORCLCP1" I mistyped "ORCLPB1 should be ORCLPDB1" yes. I wrote "ORCLCP1", need fix to "ORCLPDB1".

Need "ORACLE_PORT" description "хост" align.

Need "readme` heading "## Security" -> "## Безопасность".

Need check "ORACLE_DSN": "If set, replaces host/port/service_name" we wrote "заменяет host/port/service_name". Good. In Markdown table, a backslash needed before underscore to escape. I wrote "_" in final? Yes.

Need decide on "Connection string for a TNS alias or Easy Connect Plus" "TNS-алиаса" Good.

Need " Local use vs production" link text "См [Local..." But translate link text? The link text is prose; maybe "Локальное использование и продакшн" but anchor in original. I wrote "относительно прок." Let's maybe use "см. _Локальное использование и продакшн" with language. The link text can be translated. The target anchor should stay "#local-use-vs-production". Good.

Need "## Using with Claude Desktop" heading. I'll write "## Использование с Claude Desktop".

Need "Локально сервер общается через MCP stdio (он не открывает HTTP-порта). На прод-сервере транспорт HTTP; см. [Локальное использование и продакшн](#run local..." Good.

Need "stdin/stdout" keep.

Need "GXP6" after paragraph; yes.

Need "mas?" Need code "server.py" preserve.

Need "CLAUDE_DESKTOP_CONFIG"? no.

Need exact order: maybe original has "Running by hand" after "Using with Claude Desktop"; yes.

Need "mcp/n" maybe.

Let's prepare final clean text.

One more issue: Table column "Требуется" values "If" as "Если ..." But the row alignment. In Markdown, | no issue.

Need table service\_name escape. In final, in Markdown table, backslash may need escape? If written service\_name, display "service_name". The source source has service\_name in table cell. We should keep as service\_name. Good.

Need "Private key = primary" maybe.

Now final response: the fully translated README.

Let's ensure no code fences.

Let's produce final.# MCP-Oracle

Испанский | Английский

MCP (Model Context Protocol) — сервер, подключающий ИИ-агента к базе данных Oracle.

Он предоставляет инструменты для изучения схемы, чтения исходного кода PL/SQL и выполнения SQL. Он запускается в режиме только для чтения; запись и вызовы хранимых процедур включаются с помощью ORACLE_ALLOW_WRITE=true.

Он использует официальный Python SDK (mcp) и python-oracledb. Если он находит Instant Client (или каталог lib/ внутри ORACLE_HOME), то включает толстый режим; в противном случае используется тонкий режим. Толстый режим обязателен для более старых экземпляров (10g/11g), чей верификатор пароля не поддерживается в тонком режиме.

Этот проект — не официальный набор Oracle MCP (oracle/mcp). Этот репозиторий посвящён Oracle Cloud и другим продуктам Oracle. Этот сервер обращается напрямую к вашему экземпляру базы данных.

Инструменты

run_query и execute_dml принимают связываемые переменные (:name), чтобы вам не приходилось вставлять значения прямо в SQL.

Требования

• Python 3.9+

• Доступ к экземпляру Oracle (пользователь, пароль, хост, порт и service_name)

• Для Oracle 10g/11g (или когда тонкий режим не работает): Oracle Instant Client или каталог lib/ внутри ORACLE_HOME

Локальное использование и продакшн

В этом README описывается локальное использование: Cursor или Claude Desktop запускают server.py на вашей машине через stdio (HTTP-порт не открывается).

Если MCP должен продолжать работу на сервере, а клиенты подключаются по сети:

• Linux (RedHat)

• Windows Server

Установка

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Скопируйте шаблон переменных окружения и заполните свои значения:

cp .env.example .env

Сервер не загружает .env автоматически. Эти переменные должны быть переданы в конфигурацию MCP-клиента (Cursor, Claude Desktop и т. д.). Файл .env — это локальный справочник; не добавляйте его в коммит.

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

Толстый и тонкий режим

При запуске сервер проверяет ORACLE_CLIENT_LIB_DIR (или ~/oracle/instantclient). Если эта папка существует, вызывается oracledb.init_oracle_client() и используется толстый режим.

Примеры:

# Instant Client (zip / RPM)
ORACLE_CLIENT_LIB_DIR=/Users/your_user/oracle/instantclient

# ORACLE_HOME 19c
ORACLE_CLIENT_LIB_DIR=/apps/oracle/product/19c/lib

Если нативного клиента нет, сервер работает в тонком режиме (в большинстве случаев это Oracle 12.1+).

Использование с Cursor

В Cursor добавьте сервер в конфигурацию MCP (например, ~/.cursor/mcp.json или настройку проекта):

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Укажите абсолютный путь к Python из .venv, чтобы клиент нашёл модули mcp и oracledb.

Перезапустите Cursor (или перезагрузите MCP-серверы) и убедитесь, что oracle-mcp появляется в списке инструментов.

Использование с Claude Desktop

В claude_desktop_config.json:

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Запуск вручную

Локально сервер общается по MCP через stdio (он не открывает HTTP-порт). На сервере используется HTTP-транспорт; см. Локальное использование и продакшн.

source .venv/bin/activate
export ORACLE_USER=my_user
export ORACLE_PASSWORD=my_password
export ORACLE_HOST=127.0.0.1
export ORACLE_PORT=1521
export ORACLE_SERVICE_NAME=ORCLPDB1
python server.py

Без MCP-клиента, подключённого к stdin/stdout, вы не увидите интерактивного приглашения — это ожидаемое поведение.

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

• По умолчанию ORACLE_ALLOW_WRITE=false: execute_dml и call_procedure завершаются с PermissionError.

• run_query отклоняет запросы, начинающиеся с INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, TRUNCATE, CREATE, GRANT или REVOKE.

• execute_dml принимает только INSERT, UPDATE, DELETE или MERGE.

• Предпочитайте связываемые переменные (:id) вставке значений в SQL.

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

• Не коммитьте .env или учётные данные в version-контролируемый mcp.json.

Зависимости

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0