AI导哈

Oracle数据库自然语言查询服务器

一个连接Claude AI和Oracle数据库的MCP服务器，支持通过自然语言进行数据库查询，适用于业务利益相关者和数据库管理员。

  • by aditiashok55
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aditiashok55/oracle-mcp-server

使用说明

🗄️ Oracle MCP服务器

A. 模型上下文协议（MCP） 连接的服务器 克劳德·艾 （通过克劳德桌面） Oracle数据库 --为业务利益相关者和DBA提供与数据库的自然语言交互。

📌 概述

此项目实现了一个充当 安全桥梁 Claude AI和Oracle数据库之间。用户可以用简单的英语提问，而不是手动编写SQL，Claude将这些问题翻译成数据库查询，返回结构化、人类可读的结果。

有两种用户从中受益：

  • 🧑‍💼 业务相关方 --问以下问题 “上个季度我们收入排名前五的产品是什么？” 不知道SQL。
  • 🛠️ DBA和开发人员 --问这样的问题 “显示ORDERS表的架构” 或 “客户有哪些索引？” 加快维护和优化工作流程。

🏗️ 建筑

┌─────────────────────────────────────────────────────┐
│                   User (Natural Language)            │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│              Claude Desktop (LLM Layer)              │
│         Anthropic Claude — intent parsing,           │
│         SQL generation, result summarisation         │
└─────────────────────┬───────────────────────────────┘
                      │  MCP Protocol (stdio)
                      ▼
┌─────────────────────────────────────────────────────┐
│           Oracle MCP Server (This Project)           │
│                                                      │
│   ┌──────────────────┐   ┌───────────────────────┐  │
│   │  run_sql_query   │   │  get_table_schema     │  │
│   │  (Read Tool)     │   │  (Schema Tool)        │  │
│   │  SELECT-only     │   │  Whitelist validated  │  │
│   └────────┬─────────┘   └──────────┬────────────┘  │
│            └──────────┬─────────────┘               │
│                       ▼                             │
│              Table Whitelist Guard                  │
│              (config/settings.py)                   │
└───────────────────────┬─────────────────────────────┘
                        │  python-oracledb
                        ▼
┌─────────────────────────────────────────────────────┐
│                  Oracle Database                     │
└─────────────────────────────────────────────────────┘

✨ 特性

特性 描述
🔍 自然语言查询 通过Claude Desktop用简单的英语询问您的数据库问题
🔒 只读执行 只有 SELECT 允许声明——不允许意外的数据突变
📋 图式反思 检索任何白名单表的列名和数据类型
✅ 表白名单 可配置的允许表列表可防止未经授权的数据访问
🔌 Claude桌面集成 即插即用设置，通过 claude_desktop_config.json
🗂️ 结构化JSON响应 返回的结果包含列名、行数和行数

📁 项目结构

oracle-mcp-server/
│
├── server.py                  # MCP server entry point — tool registration & startup
│
├── tools/
│   ├── query_tool.py          # Read tool — executes SELECT queries, returns JSON
│   └── schema_tool.py         # Schema tool — fetches column info for a table
│
├── config/
│   └── settings.py            # Table whitelist configuration
│
├── test_connection.py         # Standalone Oracle connection test script
│
├── .env                       # Environment variables (not committed to git)
├── .env.example               # Template for required environment variables
└── requirements.txt           # Python dependencies

🚀 设置和安装

先决条件

1.克隆存储库

git clone https://github.com/your-username/oracle-mcp-server.git
cd oracle-mcp-server

2.安装Python依赖项

pip install -r requirements.txt

requirements.txt:

mcp[cli]
oracledb
python-dotenv

3.配置环境变量

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env:

ORACLE_CONNECTION_STRING=username/password@host:port/service_name

例子：

ORACLE_CONNECTION_STRING=admin/mypassword@localhost:1521/XEPDB1

4.配置表格白名单

编辑 config/settings.py 要列出要公开的表，请执行以下操作：

TABLE_WHITE_LIST = [
    "CUSTOMERS",
    "ORDERS",
    "PRODUCTS"
]

只有这些表可以通过模式工具访问，Claude会知道哪些表在范围内。

5.测试您的Oracle连接

在连接到Claude Desktop之前，请验证Oracle连接是否正常：

python test_connection.py

您应该看到：

Connected to Oracle database successfully!

Windows用户： 更新 lib_dir 路径在 test_connection.py 指向您的Oracle Instant Client安装目录。

6.连接到克劳德桌面

打开您的Claude Desktop配置文件：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json

在下面添加以下条目 "mcpServers":

{
  "mcpServers": {
    "oracle-mcp-server": {
      "command": "python",
      "args": ["/absolute/path/to/oracle-mcp-server/server.py"],
      "env": {
        "ORACLE_CONNECTION_STRING": "username/password@host:port/service_name"
      }
    }
  }
}

重新启动克劳德桌面。现在，您应该可以在Claude界面中看到可用的Oracle工具（查找🔌 工具图标）。

💬 示例提示和用例

🧑‍💼 面向商业利益相关者

提示 克劳德在做什么
“我们总共有多少客户？” 跑步 SELECT COUNT(*) FROM CUSTOMERS
“列出订购量最大的5种产品” 连接订单和产品，聚合和分类
“显示本月下达的所有订单” 按日期范围筛选订单

🛠️ 面向DBA和开发人员

提示 克劳德在做什么
“ORDERS表有哪些列？” 电话 get_table_schema_tool("ORDERS")
“检查CUSTOMERS表的结构” 返回所有列名和数据类型
“PRODUCTS表中是否有NULL值？” 生成带有IS NULL检查的SELECT

🔐 安全设计

安全是此服务器设计中的首要关注点：

只读执行 --The query_tool.py 拒绝任何不以开头的查询 SELECT，阻止任何DML或DDL执行（INSERT、UPDATE、DELETE、DROP等）。

表白名单 --The schema_tool.py 在执行之前，根据可配置的白名单验证每个表名。这确保了Claude只能内省您明确允许的表。

环境变量凭据 --数据库凭据从加载 .env 文件，从不在源代码中硬编码，使项目对开源是安全的。

⚠️ 注： 中的表白名单验证 query_tool.py 当前在架构级别应用。将其扩展到解析和验证任意SELECT查询中的表名已在路线图上。

🗺️ 路线图

  • [ ] 写入工具 --通过Claude进行带确认提示的受控DML执行（插入/更新）
  • [ ] 查询级表验证 --解析SELECT查询以在查询工具级别强制执行表白名单
  • [ ] 行限制执行 --限制结果集以防止大数据转储
  • [ ] 查询性能分析 --使用 EXPLAIN PLAN 向DBA显示慢速查询
  • [ ] 多模式支持 --允许配置多个数据库架构
  • [ ] 异步连接池 --用以下方式替换单个连接 oracledb.create_pool() 用于生产用途

🛠️ 技术栈

组件 技术
法学硕士 克劳德（人类学）通过克劳德桌面
MCP框架 FastMCP
Oracle驱动程序 python oracledb
配置管理 python dotenv
语言 Python 3.10+

🤝 贡献

欢迎投稿！如果您想添加写入工具、改进查询验证或扩展模式自检，请随时打开PR。

  1. 分叉回购
  2. 创建要素分支(git checkout -b feature/write-tool)
  3. 提交您的更改
  4. 打开拉取请求

📄 许可证

该项目根据MIT许可证获得许可。

👤 作者

作为展示使用模型上下文协议集成LLM数据库的投资组合项目的一部分而构建。
使用Python、Oracle DB和Anthropic的Claude开发。

相关 MCP