Oracle DB에 Claude Code 붙이기: SQLcl MCP 설치 가이드 (PowerShell)

SQLcl 25.2+ · Claude Code · 2026년 7월 기준

Oracle DB에 Claude Code 붙이기,
SQLcl 하나로 끝납니다.

별도 MCP 서버를 설치할 필요가 없습니다. SQLcl 25.2부터 MCP 서버가 내장돼 있고, 접속 정보를 설정 파일에 평문으로 적지 않아도 됩니다 — 사내 DB에 붙이기 가장 깔끔한 경로입니다.

🪟 Windows / PowerShell 🅾️ Oracle 19c ~ 23ai ⏱️ 읽는 시간 7분

Part 1 — 사전 준비

챙길 것은 세 가지

Oracle의 MCP 서버는 별도 제품이 아니라 SQLcl에 내장된 기능입니다. npm 패키지도, 커뮤니티 구현체도 필요 없고 벤더 공식이라 사내 보안 심사에서도 설명이 쉽습니다. 온프레미스든 클라우드든 Oracle 19c부터 23ai까지 동작합니다.

🧰

SQLcl 25.2 이상

MCP 서버는 25.2.0에서 들어왔습니다. 압축만 풀면 되는 무설치 도구라 사내 PC에서 설치 권한 문제가 없습니다.

이미 SQLcl이 있어도 버전을 확인하세요. 25.2 미만에는 -mcp 옵션이 없습니다.

☕

JRE 17 이상

SQLcl은 자바로 돕니다. 11이나 8이 잡혀 있으면 실행 자체가 실패합니다.

사내 PC는 레거시 앱 때문에 Java 8이 기본인 경우가 많습니다. 이때 시스템 환경변수를 바꾸지 말고 .mcp.json의 env에만 JAVA_HOME을 지정하세요.

🔐

읽기 전용 사용자

가장 중요합니다. SQLcl MCP에는 진짜 read-only 모드가 없습니다. AI가 할 수 있는 일의 상한은 접속 계정의 권한입니다.

앱 계정이나 DBA 계정을 재사용하지 말고 전용 계정을 새로 만드세요.

💡

설정 파일에 비밀번호를 적지 않아도 됩니다. SQLcl MCP 서버는 자격증명을 명령행 인자나 환경변수로 받지 않습니다. 미리 커넥션 스토어(%USERPROFILE%\.dbtools)에 저장해 두고, MCP 설정에는 실행 경로만 적습니다. DSN에 평문 비밀번호를 넣어야 하는 다른 DB MCP 서버들과 비교하면 이게 가장 큰 실무적 장점입니다.

Part 2 — 설치

PowerShell에서 5단계

아래 순서대로 실행하면 됩니다. dbhost, ORCLPDB, 비밀번호는 실제 값으로 바꿔주세요.

1

SQLcl 내려받기

설치 프로그램이 없습니다. ZIP을 풀면 끝이고 관리자 권한이 필요 없습니다 — 레지스트리도 PATH도 건드리지 않으니 사내 PC에서 막힐 일이 없고, 지울 때도 폴더째 삭제하면 됩니다.

PowerShell

# 약 130MB · 오라클 계정 로그인 불필요
curl.exe -L -o $env:TEMP\sqlcl.zip `
  "https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip"
Expand-Archive $env:TEMP\sqlcl.zip -DestinationPath C:\

# 버전 확인
C:\sqlcl\bin\sql.exe -V             # 25.2.0 이상이어야 함
java -version                       # 17 이상이어야 함

💡

C:\ 루트에 쓰기가 막힌 PC라면 C:\Users\<계정>\sqlcl 처럼 사용자 폴더에 풀어도 됩니다. 이후 나오는 경로만 맞춰 바꾸면 됩니다. Oracle SQL Developer for VS Code 확장을 이미 쓰고 있다면 SQLcl이 함께 들어 있으니 이 단계를 건너뛰어도 됩니다. 기존에 SQLcl이 있더라도 -V로 버전을 꼭 확인하세요 — 25.2 미만에는 -mcp 옵션이 아예 없습니다.

2

읽기 전용 사용자 생성

MCP 설정보다 이게 먼저입니다. 필요한 테이블만 열어주는 편이 스키마 전체를 주는 것보다 안전합니다.

SQL — DBA 계정

CREATE USER claude_ro IDENTIFIED BY "StrongPassword";
GRANT CREATE SESSION TO claude_ro;

-- 조회가 필요한 객체만 하나씩
GRANT SELECT ON app.tb_board  TO claude_ro;
GRANT SELECT ON app.tb_member TO claude_ro;

⚠️

스키마 전체를 훑게 하려고 GRANT SELECT ANY DICTIONARY나 SELECT_CATALOG_ROLE을 주는 예제가 많습니다. 데이터 딕셔너리 전체가 열리는 광범위한 권한이니 사내 DB에서는 기본적으로 주지 마세요. 권한을 준 객체는 이 계정의 ALL_TABLES·ALL_TAB_COLUMNS에 이미 보입니다.

3

커넥션 스토어에 저장

-savepwd가 필수입니다. 이 플래그 없이 저장한 커넥션은 MCP 클라이언트에서 보이지 않습니다.

PowerShell → SQLcl

C:\sqlcl\bin\sql.exe /nolog

SQL> conn -save claude_ro -savepwd claude_ro/StrongPassword@//dbhost:1521/ORCLPDB
SQL> select 1 from dual;
SQL> exit

저장된 커넥션은 connmgr list로 확인할 수 있습니다. 비밀번호에 @ / # 같은 문자가 있으면 접속 문자열 파싱이 깨지니, 따옴표로 감싸거나 영숫자로 바꿔두는 편이 편합니다.

4

Claude Code에 등록

넘기는 것은 실행 경로와 -mcp 뿐입니다. 접속 정보는 이미 커넥션 스토어에 있습니다.

PowerShell

claude mcp add sqlcl --scope local -- C:\sqlcl\bin\sql.exe -mcp

# 기본 자바가 17 미만이면 JAVA_HOME을 함께 넘긴다
claude mcp add sqlcl --scope local `
  --env JAVA_HOME="C:\Program Files\Java\jdk-17" `
  -- C:\sqlcl\bin\sql.exe -mcp

⚠️

PowerShell에서 $env:JAVA_HOME을 설정하는 것으로는 부족합니다. 그 값은 해당 창에서만 유효한데, MCP 서버는 Claude Code가 별도 자식 프로세스로 띄우기 때문입니다. 버전 확인용으로는 되지만 MCP 연결에는 전달되지 않습니다 — "확인할 땐 됐는데 붙지는 않는" 상황의 원인입니다. 자바가 여러 개인 PC라면 아래처럼 env에 넣으세요. 시스템 환경변수 JAVA_HOME은 바꾸지 마세요 — Java 8을 기대하는 다른 사내 앱이 같이 깨집니다.

.mcp.json을 직접 쓰면 이 형태입니다. 기본 자바가 이미 17 이상이면 JAVA_HOME 줄은 빼도 되고, TNS 별칭을 쓰지 않으면 TNS_ADMIN도 빼면 됩니다.

.mcp.json

{
  "mcpServers": {
    "sqlcl": {
      "command": "C:\\sqlcl\\bin\\sql.exe",
      "args": ["-mcp"],
      "env": {
        "JAVA_HOME": "C:\\Program Files\\Java\\jdk-17",
        "TNS_ADMIN": "C:\\oracle\\network\\admin"
      }
    }
  }
}

Windows에서 sql.exe의 자바 탐색 순서는 ..\..\jdk\jre\bin → %JAVA_HOME%\bin → %PATH% → %ORACLE_HOME%\jdk\jre\bin → 레지스트리입니다. JAVA_HOME이 PATH보다 앞이라 보통 위 설정으로 해결됩니다. 일부 버전에는 PATH의 java를 먼저 잡는 알려진 버그가 있으니(MOS 2985057.1), 그럴 때는 SQLcl 폴더 기준 ..\..\jdk\jre\bin에 JRE 17을 두면 확실합니다.

5

확인

목록에 잡히는지 보고, Claude Code 안에서 /mcp로 connected 상태를 확인합니다. 그 다음 커넥션을 먼저 붙여야 쿼리가 됩니다 — 서버가 뜨는 것과 DB에 접속하는 것은 별개입니다.

PowerShell → Claude Code

claude mcp list

# Claude Code 세션 안에서
/mcp

# 첫 대화는 이렇게 시작하면 됩니다
저장된 Oracle 커넥션을 보여주고 claude_ro로 접속해줘

Part 3 — 노출되는 것

도구는 딱 다섯 개

SQLcl MCP 서버가 AI에게 노출하는 도구는 다음 다섯 개입니다. 무엇이 가능한지 파악하려면 이 목록만 보면 됩니다.

도구	하는 일	위험도
list-connections	커넥션 스토어에 저장된 접속 목록 조회	낮음
connect	지정한 이름의 커넥션으로 DB 세션 연결	낮음
disconnect	현재 세션 종료	낮음
run-sql	SQL과 PL/SQL 블록 실행	계정 권한만큼
run-sqlcl	SQLcl 명령 실행 — 포맷팅, 데이터 로드, DDL 생성, Liquibase	높음

⚠️

run-sql은 SELECT 전용이 아닙니다. PL/SQL 블록까지 실행되고, run-sqlcl은 데이터 로드와 DDL 생성, Liquibase까지 닿습니다. "AI에게 조회만 시킨다"는 의도는 프롬프트가 아니라 DB 권한으로만 강제됩니다. 2단계를 건너뛰지 마세요.

💡

자동 승인(auto-approve)은 켜지 마세요. Claude Code가 도구 호출 전에 SQL을 보여주면 그때 한 번 읽고 승인하는 것이 마지막 방어선입니다.

Part 4 — 통제와 감사

restrict level과 로그

SQLcl에는 사용 가능한 명령을 단계별로 차단하는 -R 옵션이 있습니다. MCP 모드는 가장 강한 4단계가 기본값이므로 보통 건드릴 필요가 없습니다 — 낮추지 마세요.

레벨	차단하는 것
0	없음
1	OS 명령 (host, !, $, edit)
2	1단계 + 파일 저장 (save, spool, store)
3	2단계 + 스크립트 실행 (@, @@, get, start)
4	3단계 + 100여 개 명령 추가 차단 — MCP 기본값

누가 무엇을 했는지 보기

Oracle 쪽 감사 수단이 두 가지 있습니다. V$SESSION에는 어떤 MCP 클라이언트와 어떤 LLM이 붙었는지 남고, SQLcl은 상호작용을 별도 로그 테이블에 기록합니다.

SQL — 감사

-- 어떤 클라이언트/LLM이 붙어 있나
SELECT sid, username, module, action, program
  FROM v$session WHERE module LIKE '%MCP%';

-- SQLcl이 남기는 상호작용 로그
SELECT * FROM dbtools$mcp_log
 ORDER BY 1 DESC FETCH FIRST 20 ROWS ONLY;

⚠️

여기에 트레이드오프가 있습니다. DBTOOLS$MCP_LOG는 접속한 사용자 스키마에 만들어집니다. 그래서 테이블 생성 권한이 전혀 없는 순수 읽기 전용 계정으로 붙이면 이 로그가 남지 않을 수 있습니다. 감사 기록이 반드시 필요하면 자기 스키마 한정으로 최소 쿼터와 CREATE TABLE을 주거나, 계정은 그대로 두고 Unified Auditing으로 대체하세요.

배포 전 체크리스트

✓

전용 계정으로만 접속 — 앱 계정·DBA 계정 재사용 금지. AI의 권한 상한은 이 계정입니다.

✓

운영 DB 직결은 피하기 — 개발·스테이징이나 마스킹된 복제본부터. 운영 접속은 DBA 승인 대상입니다.

✓

restrict level을 낮추지 않기 — -R 1 같은 예제를 복사하면 OS 명령까지 열립니다.

✓

자동 승인 끄기 — run-sqlcl은 DDL과 데이터 로드까지 닿습니다.

Part 5 — 삽질 포인트

막히는 지점은 정해져 있습니다

대부분 MCP가 아니라 자바·경로·커넥션 스토어 문제입니다. 증상만 알면 원인이 바로 잡힙니다.

☕

Unsupported Java version

JRE 17 미만입니다. .mcp.json의 env에 JAVA_HOME을 넣으세요. PowerShell에서 $env:로 설정한 값은 MCP 서버 프로세스에 전달되지 않습니다.

🗂️

list-connections가 비어 있다

-savepwd 없이 저장했거나, 다른 Windows 사용자로 저장한 경우입니다. 스토어는 %USERPROFILE%\.dbtools에 있습니다.

🧩

서버가 뜨지 않는다

sql.exe 절대 경로를 쓰세요. sql만 적으면 PATH에 없어서 실패합니다.

🔗

TNS 별칭으로 접속 실패

TNS_ADMIN을 env로 넘겨야 합니다. MCP 서버는 사용자 셸 환경을 그대로 물려받지 않습니다.

🔑

ORA-01017 / ORA-28001

스토어에 저장된 비밀번호가 바뀌었거나 만료됐습니다. conn -save로 다시 저장하세요.

🧾

테이블이 안 보인다

권한을 준 객체는 다른 스키마 소유입니다. app.tb_board처럼 스키마 접두어를 쓰거나 시노님을 만들어주세요.

여기까지 오면 DB가 대화 가능해집니다

스키마를 설명하게 하고, 통계 쿼리를 맡기고, 실행계획을 읽혀보세요.
시작은 전용 계정 하나와 커넥션 저장 한 줄입니다.