homemade-mcp-oracle-database-10g-claude

MCP 서버 및/또는 Claude Code 스킬을 통해 터미널에서 직접 Oracle Database 10g 데이터베이스를 조회하기 위한 읽기 전용 유틸리티입니다. 원래 요구 사항은 requeriments.txt를 참조하세요.

왜 이런 것이 필요한가

Oracle 10g는 10년 이상 전에 확장 지원이 종료되었습니다. 최신 Oracle 드라이버(python-oracledb, node-oracledb)는 기본적으로 Oracle 12c 이후의 네트워크 프로토콜만 지원하는 "thin" 모드를 사용합니다. 10g와 통신하려면 로컬에 설치된 Oracle Instant Client를 기반으로 "thick" 모드를 강제해야 합니다. 대부분의 일반 Oracle MCP는 이 옵션을 노출하지 않기 때문에, 이 맞춤형 유틸리티가 필요했습니다.

이 프로젝트에서 확인된 사항: Oracle Instant Client 19.x는 thick 모드에서 Oracle Database 10g Release 10.2.0.3.0에 연결에 성공합니다 (예상과 달리 Instant Client 11.2로 낮출 필요가 없었습니다).

Related MCP server: MCP Oracle Server

아키텍처

src/
  config.py           Carga y valida .env (conexion, Instant Client, politica)
  db.py                Conexion Oracle en modo thick (oracledb.init_oracle_client)
  sql_guard.py         Guard de solo-lectura: solo permite SELECT / WITH
  audit_log.py         Logging de auditoria (logs/query_audit.log)
  query_runner.py      Ejecuta SQL con limite de filas (MAX_ROWS), timeout y auditoria
  schema_inspector.py  Consultas de catalogo (list_tables / describe_table), SQL 10g-safe
  mcp_server.py        Servidor MCP (tools: run_query_tool, list_tables, describe_table)

scripts/
  test_connection.py   Prueba minima de conectividad (Fase 0)
  query.py             CLI de consultas (Fase 1) usado tambien por la skill

.claude/skills/oracle10g-query/SKILL.md   Skill de Claude Code (usa scripts/query.py)

CLI와 MCP 서버는 모두 동일한 코어(config -> db -> sql_guard/query_runner)를 재사용하므로 보안 정책과 제한이 한 곳에서 한 번만 적용됩니다.

보안 모델 (심층 방어)

1. 데이터베이스 수준: 구성된 Oracle 사용자는 이미 DBA가 부여한 읽기 전용 권한을 가지고 있습니다. 이것이 주요하고 실제적인 장벽입니다.

2. 소프트웨어 수준(src/sql_guard.py): "자유" SQL(run_query/run_query_tool로 들어오는 것)을 보내기 전에 단일 SELECT 또는 WITH ... SELECT 문인지 검증합니다. INSERT/UPDATE/DELETE/MERGE, DDL, GRANT/REVOKE, PL/SQL(BEGIN, EXEC, ...) 또는 ;로 이어진 복수 문장은 모두 거부됩니다. 카탈로그 쿼리(list_tables/describe_table)는 이 가드를 거치지 않습니다. 해당 SQL은 이 유틸리티 자체가 작성한 고정 SQL이기 때문이며, 매개변수(schema/table_name)만 바인드 변수로 전달됩니다.

3. 실행 제한: MAX_ROWS는 반환되는 행 수를 제한하고(fetchmany 사용, 적용 시 결과에 truncated: true로 표시), QUERY_TIMEOUT_SECONDS는 쿼리가 멈추면 중단합니다(cursor.callTimeout).

4. 감사: 모든 실행(성공, Oracle 오류, 또는 가드에 의한 거부)은 logs/query_audit.log에 사용자, SQL, 결과와 함께 기록됩니다.

설치

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
copy .env.example .env

실제 데이터로 .env를 편집하세요(.env.example의 주석 참조): 호스트/포트/service_name 또는 SID, 읽기 전용 사용자 이름과 비밀번호, 그리고 Oracle Instant Client 경로(ORACLE_INSTANT_CLIENT_DIR). .env를 저장소에 절대 올리지 마세요.

사용법

1. 연결 테스트

.venv\Scripts\python scripts\test_connection.py

2. 쿼리 CLI

.venv\Scripts\python scripts\query.py "SELECT * FROM alguna_tabla WHERE ROWNUM <= 10" --format json
.venv\Scripts\python scripts\query.py --file consulta.sql --format table

3. MCP 서버

수동으로 실행 (stdio):

.venv\Scripts\python -m src.mcp_server

MCP 클라이언트(Claude Desktop, Claude Code 등)에 등록하려면 mcp-config.example.json을 참조하세요 — 경로를 자신의 머신에 맞게 조정하고 해당 블록을 클라이언트의 mcpServers 설정에 추가하세요.

노출된 도구:

• run_query_tool(sql) — SELECT를 실행합니다(읽기 전용 가드가 적용됨).

• list_tables(schema?) — 카탈로그의 테이블을 나열합니다(all_tables).

• describe_table(table_name, schema?) — 테이블의 컬럼을 표시합니다(all_tab_columns).

4. Claude Code 스킬

.claude/skills/oracle10g-query/SKILL.md를 참조하세요. Claude Code에 이 데이터베이스의 데이터를 조회하거나 확인하도록 요청할 때 활성화되며, 내부적으로 동일한 scripts/query.py를 사용합니다.

알아둬야 할 Oracle 10g 특이사항

Oracle 10g는 FETCH FIRST n ROWS ONLY / OFFSET(12c+ 구문)을 지원하지 않습니다. 쿼리에서 행 수를 제한하려면 ROWNUM을 사용하세요:

SELECT * FROM (
  SELECT col1, col2 FROM tabla ORDER BY col1
) WHERE ROWNUM <= 20