Oracle MCP Server Deer

MCP服务器-Oracle数据库上下文

英语 | 中文

一个强大的模型上下文协议（MCP）服务器，为大型Oracle数据库提供上下文数据库模式信息，使AI助手能够理解和使用包含数千个表的数据库。

✨ 新增：多数据库支持 -同时连接到多个Oracle数据库！看 多数据库指南 了解详情。

目录

• 概述
• 特性
• 用法

- - - 选项2：使用UV（本地安装） - 在本地启动服务器 - 可用工具

• 多数据库支持
• 建筑
• 连接模式

- 精简模式（默认） - 厚模式

• 系统要求
• 性能注意事项
• 贡献
• 许可证
• 支持

概述

MCP Oracle DB Context服务器解决了处理非常大的Oracle数据库时的一个关键挑战：如何为AI模型提供准确、相关的数据库模式信息，而不会让成千上万的表和关系压倒它们。

通过智能缓存和提供数据库模式信息，该服务器允许AI助手：

• 按需查找特定的表模式
• 搜索与特定模式匹配的表
• 了解表关系和外键
• 获取数据库供应商信息
• 新 同时查询多个Oracle数据库（prod、test、dev等）

特性

• 多数据库支持：从单个MCP服务器实例连接到并查询多个Oracle数据库
• 智能架构缓存：构建和维护数据库架构的本地缓存，以尽量减少数据库查询
• 目标架构查找：检索特定表的架构，而不加载整个数据库结构
• 表格搜索：按名称模式匹配查找表
• 关系映射：了解表之间的外键关系
• Oracle数据库支持：专为Oracle数据库构建
• MCP集成：在VSCode、Claude、ChatGPT和其他支持MCP的AI助手中与GitHub Copilot无缝协作
• 只读模式：默认安全模式，在允许完全读取访问的同时阻止写入操作

多数据库支持

服务器现在支持同时连接到多个Oracle数据库。这使得：

• 跨环境查询（生产、测试、开发）
• 跨数据库的架构比较
• 环境之间的数据验证
• 为每个数据库分别设置模式缓存

有关多数据库设置和使用的完整文档，请参阅 多数据库指南.

快速入门（多数据库）：

# In .env file
DB_NAMES=prod,test,dev
DB_PROD_CONNECTION_STRING=user/pass@prod-host:1521/PRODPDB
DB_TEST_CONNECTION_STRING=user/pass@test-host:1521/TESTPDB
DB_DEV_CONNECTION_STRING=user/pass@dev-host:1521/DEVPDB

向后兼容性： 单个数据库配置继续工作，没有任何更改。

用法

在VSCode内部人员中与GitHub Copilot集成

要在VSCode Insiders中将此MCP服务器与GitHub Copilot一起使用，请执行以下步骤：

1. 安装VSCode内部插件

- 下载并安装最新版本的 VSCode内部人员

1. 安装GitHub副本扩展

- 开放VSCode内部人员 - 前往扩展市场 - 搜索并安装“GitHub Copilot”

1. 配置MCP服务器

- 推荐： - 备选方案： 使用UV

1. 启用代理模式

- 在VSCode Insiders中打开Copilot聊天 - 点击“复制编辑” - 选择“代理模式” - 单击聊天输入中的刷新按钮以加载可用工具

完成这些步骤后，您将可以通过GitHub Copilot的聊天界面访问所有数据库上下文工具。

选项1：使用Docker（推荐）

在VSCode Insiders中，转到您的用户或工作区 settings.json 文件并添加以下内容：

"mcp": {
    "inputs": [
     {
       "id": "db-password",
       "type": "promptString",
       "description": "Oracle DB Password",
       "password": true,
     }
   ],
    "servers": {
        "oracle": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "ORACLE_CONNECTION_STRING",
                "-e",
                "TARGET_SCHEMA",
                "-e",
                "CACHE_DIR",
                "-e",
                "THICK_MODE",
                "dmeppiel/oracle-mcp-server"
            ],
            "env": {
               "ORACLE_CONNECTION_STRING":"/${input:db-password}@:1521/",
               "TARGET_SCHEMA":"",
               "CACHE_DIR":".cache",
               "THICK_MODE":"",  // Optional: set to "1" to enable thick mode
               "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and you want to set a non-default directory for client libraries
               "READ_ONLY_MODE":"1"  // Optional: set to "0" to allow write operations (default: "1" for read-only)
            }
        }
    }
}

使用Docker时（推荐方法）：

• 所有依赖项都包含在容器中
• 集 THICK_MODE=1 在环境变量中启用厚模式（如果需要）
• 如果你使用 THICK_MODE，您可以选择设置Oracle客户端库的安装路径 ORACLE_CLIENT_LIB_DIR 如果它与默认位置不同。

选项2：使用UV（本地安装）

此选项需要在本地安装和设置项目：

1. 先决条件

- Python 3.12或更高版本 - Oracle数据库访问 - Oracle即时客户端（ oracledb Python包）

1. 安装UV

   # Install uv using curl (macOS/Linux)
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Or using PowerShell (Windows)
   irm https://astral.sh/uv/install.ps1 | iex

安装uv后，请确保重新启动终端。

1. 项目设置

   # Clone repository
   git clone https://github.com/yourusername/oracle-mcp-server.git
   cd oracle-mcp-server

   # Create and activate virtual environment
   uv venv

   # Activate (On Unix/macOS)
   source .venv/bin/activate

   # Activate (On Windows)
   .venv\Scripts\activate

   # Install dependencies
   uv pip install -e .

1. 配置VSCode设置

   "mcp": {
      "inputs": [
         {
            "id": "db-password",
            "type": "promptString",
            "description": "Oracle DB Password",
            "password": true,
         }
      ],
      "servers": {
         "oracle": {
               "command": "/path/to/your/.local/bin/uv",
               "args": [
                  "--directory",
                  "/path/to/your/oracle-mcp-server",
                  "run",
                  "main.py"
               ],
               "env": {
                  "ORACLE_CONNECTION_STRING":"/${input:db-password}@:1521/",
                  "TARGET_SCHEMA":"",
                  "CACHE_DIR":".cache",
                  "THICK_MODE":"",  // Optional: set to "1" to enable thick mode
                  "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and if you want to set a non-default directory for client libraries
                  "READ_ONLY_MODE":"1"  // Optional: set to "0" to allow write operations (default: "1" for read-only)
               }
         }
      }
   }

• 将路径替换为实际的uv二进制路径和oracle mcp服务器目录路径

对于这两个选项：

• 更换 ORACLE_CONNECTION_STRING 使用实际的数据库连接字符串
• 这 TARGET_SCHEMA 是可选的，它将默认为用户的模式
• 这 CACHE_DIR 是可选的，默认为 .cache 在MCP服务器根文件夹中
• 这 READ_ONLY_MODE 为了安全起见，默认为“1”（只读）。仅在需要写入操作时设置为“0”

在本地启动服务器

要直接运行MCP服务器：

uv run main.py

对于开发和测试：

# Install the MCP Inspector
uv pip install mcp-cli

# Test with MCP Inspector
mcp dev main.py

# Or install in Claude Desktop
mcp install main.py

可用工具

当连接到VSCode Insiders或Claude中的GitHub Copilot等AI助手时，将提供以下工具：

get_table_schema

获取特定表的详细架构信息，包括列、数据类型、可空性和关系。 例子：

Can you show me the schema for the EMPLOYEES table?

get_tables_schema

一次获取多个表的架构信息。比多次调用get_table_schema更有效。 例子：

Please provide the schemas for both EMPLOYEES and DEPARTMENTS tables.

search_tables_schema

按名称模式搜索表并检索其模式。 例子：

Find all tables that might be related to customers and show their schemas.

rebuild_schema_cache

强制重建架构缓存。节约使用，因为这是资源密集型的。 例子：

The database structure has changed. Could you rebuild the schema cache?

get_database_vendor_info

获取有关连接的Oracle数据库版本和架构的信息。 例子：

What Oracle database version are we running?

search_columns

搜索包含与特定术语匹配的列的表。当你知道你需要什么数据，但不确定哪些表包含它时，这很有用。 例子：

Which tables have columns related to customer_id?

get_pl_sql_objects

获取有关PL/SQL对象的信息，如过程、函数、包、触发器等。 例子：

Show me all stored procedures that start with 'CUSTOMER_'

get_object_source

检索PL/SQL对象的源代码。有助于调试和理解数据库逻辑。 例子：

Can you show me the source code for the CUSTOMER_UPDATE_PROC procedure?

get_table_constraints

获取表的所有约束（主键、外键、唯一约束、检查约束）。 例子：

What constraints are defined on the ORDERS table?

get_table_indexes

获取表上定义的所有索引，有助于查询优化。 例子：

Show me all indexes on the CUSTOMERS table.

get_dependent_objects

查找依赖于指定数据库对象的所有对象。 例子：

What objects depend on the CUSTOMER_VIEW view?

get_user_defined_types

获取数据库中用户定义类型的信息。 例子：

Show me all custom types defined in the schema.

get_related_tables

通过外键获取与指定表相关的所有表，显示传入和传出关系。 例子：

What tables are related to the ORDERS table?

run_sql_query

执行SQL查询，并在格式化的表中返回结果。 例子：

Can you run this query for me? SELECT * FROM EMPLOYEES WHERE DEPARTMENT_ID = 10

备注：在只读模式（默认）下，只允许使用SELECT语句。出于安全考虑，写入操作（INSERT、UPDATE、DELETE）被阻止。当只读模式被禁用时(READ_ONLY_MODE="0")，此工具可以执行读取和写入操作。

建筑

此MCP服务器采用针对大型Oracle数据库优化的三层架构：

1. 数据库连接器层

- 管理Oracle数据库连接和查询执行 - 实现连接池和重试逻辑 - 处理原始SQL操作

1. 架构管理器层

- 实现智能模式缓存 - 提供优化的架构查找和搜索 - 管理磁盘上的持久缓存

1. 数据库上下文层

- 展示高级MCP工具和接口 - 处理授权和访问控制 - 为AI消费提供模式优化

连接模式

数据库连接器支持两种连接模式：

精简模式（默认）

默认情况下，连接器使用Oracle的瘦模式，这是一个纯Python实现。此模式为：

• 更易于设置和部署
• 足以进行大多数基本的数据库操作
• 在不同环境中更便携

厚模式

对于需要高级Oracle功能或更好性能的场景，您可以启用厚模式：

• 使用Docker时（推荐）：设置 THICK_MODE=1 在Docker环境变量中
• 使用本地安装时：导出 THICK_MODE=1 环境变量，并确保安装了与您的系统体系结构和数据库版本兼容的Oracle客户端库

您可以使用以下命令为Oracle客户端库指定自定义位置 ORACLE_CLIENT_LIB_DIR 环境变量。这在以下情况下特别有用：

• 您在非标准位置安装了Oracle客户端库
• 您需要在同一系统上使用多个Oracle客户端版本
• 您没有在标准位置安装Oracle客户端的管理权限
• 您需要特定的Oracle客户端版本才能与某些数据库功能兼容

注意：使用Docker时，您不必担心安装Oracle客户端库，因为它们包含在容器中（Oracle Instant Client v23.7）。该容器支持linux/arm64和linux/amd64架构中的Oracle数据库版本19c至23ai。

只读模式

默认情况下，MCP服务器以只读模式运行，以提高安全性。这可以防止任何写入操作（INSERT、UPDATE、DELETE、DDL），同时允许对数据库进行完全读取访问。它可以防止AI生成的查询发生意外更改。

配置

• 默认: READ_ONLY_MODE="1" （只读，安全）
• 写入访问: READ_ONLY_MODE="0" （允许写入操作）

系统要求

• python：3.12或更高版本（最佳性能所需）
• 记忆：4GB以上可用RAM用于大型数据库（10000多个表）
• 磁盘：架构缓存的最小可用空间为500MB
• 甲骨文：与Oracle数据库11g及更高版本兼容
• 网络：与Oracle数据库服务器的稳定连接

性能注意事项

• 对于非常大的数据库，初始缓存构建可能需要5-10分钟
• 后续创业通常需要不到30秒的时间
• 模式查找通常在缓存后的亚秒级
• 内存使用量随活动架构大小而变化

贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

对于问题和疑问：

• 在此GitHub存储库中创建问题