Oracle MCP Sdm With Guardrails

具有高级安全功能的Oracle MCP服务器

一种用于Oracle数据库的模型上下文协议（MCP）服务器，具有全面的查询安全功能，旨在通过StrongDM代理和Apple Silicon Mac工作。

🔒 安全审核： ✅ 已修复所有漏洞（2025-11-21）

🛡️ 为什么选择MCP？

与其他数据库MCP服务器不同，此实现包括 生产级安全特性:

• ✅ SQL注入保护 -对所有入口点进行严格的输入验证
• ✅ 方块笛卡尔积 -防止可能锁定数据库的意外交叉连接
• ✅ 查询复杂性评分 -在执行前拒绝过于复杂的查询
• ✅ 结果集限制 -自动强制最大行返回（默认值为10000）
• ✅ 只读执行 -阻止所有写操作（DELETE、UPDATE、INSERT、DROP、UNION等）
• ✅ 多层验证 -模式检测、关键字屏蔽和复杂性分析
• ✅ 凭证安全 -密码从未在进程列表中公开
• ✅ 评论删除 -防止基于SQL注释的绕过
• ✅ 详细日志记录 -所有被阻止的查询都会记录原因

安全研究： 43%的流行MCP服务器包含SQL注入漏洞。此实现采用安全第一设计构建，并通过了全面的安全审计。

🏗️ 建筑

此MCP使用 Java子流程模式 通过JDBC连接到Oracle：

┌─────────────────┐
│ Claude/AI Agent │
└────────┬────────┘
         │ MCP Protocol
┌────────▼────────────────┐
│ oracle_mcp_server.py    │  ← Python MCP Server
│  + Query Validator      │  ← SAFETY LAYER
└────────┬────────────────┘
         │ Subprocess
┌────────▼────────────────┐
│  Java JDBC Process      │  ← OracleQuery.java
│  ojdbc11.jar            │
└────────┬────────────────┘
         │ TCP/StrongDM
┌────────▼────────────────┐
│  Oracle Database        │
└─────────────────────────┘

为什么选择Java子进程？

创建此实现是因为 现有的MCP解决方案不起作用 使用StrongDM+苹果硅：

• ❌ mcp炼金术 使用Python oracledb → 失败（StrongDM不兼容）
• ❌ Python Java桥 （JPype1，PyJNIus）→ 撞上苹果硅
• ✅ Java JDBC子进程 → 使用经过验证的DataGraph JDBC驱动程序

优点：

• 适用于Python库失败的StrongDM代理
• 经过验证的稳定性（与JetBrains DataGraph相同的驱动程序）
• 进程隔离可防止崩溃
• Apple Silicon上没有原生库的复杂性

🚀 快速开始

先决条件

• Java 21+（建议使用OpenJDK）
• Python 3.12+
• Oracle JDBC驱动程序（ojdbc11）
• 访问Oracle数据库（直接或通过StrongDM代理）

安装

1. 克隆存储库：

   git clone https://github.com/mofiaboss/oracle-mcp-sdm-with-guardrails.git
   cd oracle-mcp-sdm-with-guardrails

1. 创建虚拟环境：

   # Use python3.10 or later (python3.12 recommended)
   python3.12 -m venv oracle_mcp_venv
   source oracle_mcp_venv/bin/activate  # On Windows: oracle_mcp_venv\Scripts\activate

1. 安装Python依赖项：

   pip install -r requirements.txt

1. 下载Oracle JDBC驱动程序：

- 下载 ojdbc11-23.5.0.24.07.jar （或稍后）从 甲骨文 - 放置在项目目录中或记下路径

1. 下载JSON库：

- 下载 json-20240303.jar 从 Maven中央仓库 - 重命名为 json.jar 并放置在项目目录中

1. 编译Java查询程序：

   export JDBC_JAR="/path/to/ojdbc11-23.5.0.24.07.jar"
   javac -cp ".:json.jar:$JDBC_JAR" OracleQuery.java

1. 配置环境变量：

   cp .env.example .env
   # Edit .env with your Oracle connection details

1. 更新路径 oracle_jdbc.py:

编辑第38-47行以匹配您的Java和JDBC路径：

   self.java_home = Path("/opt/homebrew/opt/openjdk@21")
   self.jdbc_jar = Path("/path/to/ojdbc11-23.5.0.24.07.jar")

测试

# Test safety features
python test_safety.py

# Test Python wrapper
python oracle_jdbc.py

🔧 配置

Claude桌面配置

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "oracle": {
      "command": "/path/to/oracle_mcp_venv/bin/python",
      "args": [
        "/path/to/oracle_mcp_server.py"
      ],
      "env": {
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "10006",
        "ORACLE_SERVICE_NAME": "ORCL",
        "ORACLE_USER": "your_username",
        "ORACLE_PASSWORD": "your_password"
      }
    }
  }
}

环境变量

安全配置

调整安全设置 oracle_mcp_server.py （第48-52行）：

validator = QueryValidator(
    max_complexity=50,      # Maximum complexity score (lower = stricter)
    max_rows=10000,         # Maximum result rows
    allow_cross_joins=False # Enable to allow CROSS JOIN (not recommended)
)

🛡️ 安全功能

看 安全_食品S.md 以获取完整的文档。

什么被阻止

-- ❌ Cartesian products
SELECT * FROM orders, customers

-- ❌ Explicit cross joins
SELECT * FROM users CROSS JOIN orders

-- ❌ All write operations
DELETE FROM users WHERE id = 1
UPDATE orders SET status = 'X'
INSERT INTO users VALUES (1, 'test')
DROP TABLE sensitive_data
TRUNCATE TABLE logs

-- ❌ Overly complex queries (score > 50)
SELECT * FROM t1, t2, t3, t4 WHERE t1.id = 1

允许的内容（带警告）

-- ✅ Simple queries
SELECT * FROM users WHERE id = 123

-- ✅ Proper joins with conditions
SELECT * FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE o.status = 'PENDING'

-- ✅ Aggregate queries
SELECT COUNT(*) FROM orders WHERE created_date > SYSDATE - 7

查询复杂性评分

查询的评分基于：

• +5 每张桌子点数
• +20 每个逗号分隔表的点数（隐式连接）
• +10 每子查询点数
• +5 得分 DISTINCT
• +3 每个聚合函数的点数
• +10 得分 SELECT * 有多张桌子

最高得分： 50 （可配置）

📊 查询响应格式

成功的查询返回验证元数据：

{
  "success": true,
  "row_count": 42,
  "rows": [...],
  "validation": {
    "complexity_score": 15,
    "warnings": [
      "Query involves 2 tables. Ensure proper JOIN conditions exist."
    ],
    "row_limit_applied": 10000
  }
}

被阻止的查询返回详细错误：

{
  "success": false,
  "error": "Dangerous pattern detected: CROSS JOIN...",
  "complexity_score": 0,
  "warnings": []
}

🔌 可用的MCP工具

🎯 推荐的查询工作流

为了获得最大的安全性，请务必在执行前预览查询：

1. 先预览： 使用 preview_query 验证并查看复杂性得分
2. 评审： Claude将向您展示查询和复杂性的详细信息
3. 确认： 明确批准查询执行
4. 执行： 克劳德将使用 query_oracle 运行它

这个两步工作流程确保您始终知道将对数据库运行什么。

preview_query ⭐ 先用这个

预览和验证SQL查询，而无需执行它们。显示：

• 将执行的确切查询
• 复杂性得分（0-50，越低越简单）
• 任何验证警告或错误
• 是否应用行限制
• 安全评估

例子：

Preview this query: SELECT * FROM customers WHERE country = 'US'

答复包括：

{
  "preview_mode": true,
  "query_to_execute": "SELECT * FROM customers WHERE country = 'US'",
  "validation": {
    "is_safe": true,
    "complexity_score": 8,
    "max_complexity": 50,
    "complexity_explanation": "Lower is simpler. Score based on: JOINs (+5 each), subqueries (+3 each), GROUP BY (+2), aggregates (+1 each)",
    "warnings": ["Table 'customers' used - ensure proper WHERE clause"]
  },
  "safety_limits": {
    "max_rows": 10000,
    "row_limit_will_be_applied": true
  }
}

query_oracle

执行带有安全验证的SQL SELECT查询。

重要提示： 只能在使用后调用 preview_query 并获得用户确认。

例子：

Query the database: SELECT * FROM customers WHERE country = 'US'

describe_table

获取表结构、列、数据类型和主键。

例子：

Describe the ORDERS table structure

list_tables

列出数据库中所有可访问的表。

例子：

List all tables in the current schema

📁 项目结构

oracle-mcp-server/
├── oracle_mcp_server.py    # Main MCP server
├── oracle_jdbc.py           # JDBC wrapper
├── query_validator.py       # Safety validation layer
├── OracleQuery.java         # Java JDBC query program
├── OracleQuery.class        # Compiled Java class
├── json.jar                 # JSON library for Java
├── test_safety.py           # Safety feature tests
├── SAFETY_FEATURES.md       # Detailed safety documentation
├── README.md                # This file
├── requirements.txt         # Python dependencies
└── .env.example            # Environment configuration template

🐛 故障排除

连接失败

1. 验证Java安装：

   java -version
   # Should show Java 21+

1. 测试数据库连接：

   # Via SQLPlus or another tool
   sqlplus username/password@//host:port/service_name

1. 检查StrongDM（如果使用）：

   ps aux | grep sdm
   nc -zv 127.0.0.1 10006

1. 验证JDBC jar路径：

   ls -la /path/to/ojdbc11*.jar

Java错误

• 类未找到异常：JDBC jar不在类路径中
• 不满足链接错误：Java版本不匹配
• 连接被拒绝：在指定的主机/端口上无法访问数据库

MCP服务器未加载

1. 完全重新启动克劳德桌面
2. 检查Claude Desktop中的日志是否有错误
3. 直接测试Python脚本： python oracle_mcp_server.py
4. 验证已安装的所有依赖项： pip list

🤝 贡献

欢迎投稿！需要改进的地方：

• \[\]添加对更多数据库类型的支持
• \[\]实现连接池
• \[\]添加查询计划分析
• \[\]创建Docker容器
• \[\]添加指标/监控端点
• \[\]支持Oracle钱包身份验证

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🙏 致谢

• 为解决Apple Silicon上StrongDM代理兼容性问题而构建
• 受Datadog安全实验室关于MCP漏洞的安全研究启发
• 基于OWASP SQL注入预防指南的查询验证模式
• 使用JetBrains DataGraph中经过验证的Oracle JDBC驱动程序

📚 相关文件

• 模型上下文协议
• Oracle JDBC驱动程序
• OWASP SQL注入防护
• StrongDM
• MCP安全最佳实践

______________________________________________________________________

安全说明： 默认情况下，此MCP服务器阻止写入操作。如果你需要写访问权限，你应该实现适合你环境的额外身份验证和授权层。