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

只读工具，用于从 MCP 服务器和/或直接通过 Claude Code 的 skill 从终端查询 Oracle Database 10g 数据库。原始需求见 requeriments.txt。

为什么会有这个工具

Oracle 10g 在十多年前就已停止扩展支持。现代 Oracle 驱动（python-oracledb、node-oracledb）默认使用 "thin" 模式，该模式只支持 Oracle 12c 及以上的网络协议。要与 10g 通信，需要强制使用 “thick”模式，并依赖本地安装的 Oracle Instant Client。大多数通用 Oracle MCP 不暴露该选项，因此有了这个定制工具。

本项目已确认：thick 模式下的 Oracle Instant Client 19.x 确实能够连接 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 传入的 SQL）之前，会验证它必须是单个 SELECT 或 WITH ... SELECT 语句。任何 INSERT/UPDATE/DELETE/MERGE、DDL、GRANT/REVOKE、PL/SQL（BEGIN、EXEC 等）或使用 ; 堆叠的语句都会被拒绝。目录查询（list_tables/describe_table）不经过此 guard，因为其 SQL 是固定且由本工具自身编写的；只有其参数（schema/table_name）作为绑定变量传入。

3. 执行限制：MAX_ROWS 限制返回的行数（通过 fetchmany，如果适用，结果会显示 truncated: true），QUERY_TIMEOUT_SECONDS 在查询挂起时中断查询（cursor.callTimeout）。

4. 审计：所有执行（成功、Oracle 错误、或被 guard 拒绝）都会记录在 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 中的注释）：host/port/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（应用只读 guard）。

• list_tables(schema?) — 列出目录中的表（all_tables）。

• describe_table(table_name, schema?) — 表的列（all_tab_columns）。

4. Claude Code Skill

参见 .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