MCP-Oracle

Español | English

MCP(Model Context Protocol) 서버로, AI 에이전트를 Oracle 데이터베이스에 연결합니다.

스키마 탐색, PL/SQL 소스 읽기, SQL 실행을 위한 도구를 제공합니다. 기본적으로 읽기 전용 모드로 시작하며, 쓰기 및 저장 프로시저 호출은 ORACLE_ALLOW_WRITE=true로 활성화됩니다.

공식 Python SDK(mcp)와 python-oracledb를 사용합니다. Instant Client(또는 ORACLE_HOME의 lib/ 디렉토리)를 찾으면 thick 모드를 활성화하고, 그렇지 않으면 thin 모드를 사용합니다. thin 모드에서 지원되지 않는 비밀번호 검증기를 사용하는 구형 인스턴스(10g/11g)에는 thick 모드가 필요합니다.

이 프로젝트는 공식 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(또는 thin 모드가 실패하는 경우): Oracle Instant Client 또는 ORACLE_HOME의 lib/ 디렉토리

로컬 사용 vs 프로덕션

이 README는 로컬 사용을 다룹니다: Cursor 또는 Claude Desktop이 stdio를 통해 사용자 머신에서 server.py를 시작합니다(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 파일은 로컬 참조용이며 커밋하지 마세요.

환경 변수

Thick vs thin 모드

시작 시 서버는 ORACLE_CLIENT_LIB_DIR(또는 ~/oracle/instantclient)을 확인합니다. 해당 폴더가 존재하면 oracledb.init_oracle_client()를 호출하고 thick 모드를 사용합니다.

예:

# 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

네이티브 클라이언트가 없으면 thin 모드로 실행됩니다(대부분의 경우 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"
      }
    }
  }
}

.venv Python의 절대 경로를 사용하여 클라이언트가 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"
      }
    }
  }
}

수동 실행

로컬에서 서버는 stdio를 통해 MCP를 사용합니다(HTTP 포트를 열지 않음). 프로덕션 서버에서는 전송이 HTTP입니다. 로컬 사용 vs 프로덕션을 참조하세요.

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

stdin/stdout에 연결된 MCP 클라이언트가 없으면 대화형 프롬프트가 표시되지 않습니다. 이는 정상입니다.

보안

• 기본적으로 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만 허용합니다.

• SQL에 값을 보간하는 대신 바인드 변수(:id)를 사용하세요.

• 스키마 탐색만 필요한 경우 최소 권한 사용자로 연결하세요.

• 버전 관리되는 mcp.json에 .env 또는 자격 증명을 커밋하지 마세요.

종속성

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0