使用说明

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

英语 | 中文

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

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

概述

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一起使用，请执行以下步骤：

安装VSCode内部插件
- 下载并安装最新版本的 VSCode内部人员
安装GitHub副本扩展
- 开放VSCode内部人员
- 前往扩展市场
- 搜索并安装“GitHub Copilot”
配置MCP服务器
- 推荐：使用Docker
- 备选方案：使用UV
启用代理模式
- 在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":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
               "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（本地安装）

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

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

安装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后，请确保重新启动终端。

项目设置

# 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 .

配置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":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
               "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数据库优化的三层架构：

数据库连接器层
- 管理Oracle数据库连接和查询执行
- 实现连接池和重试逻辑
- 处理原始SQL操作
架构管理器层
- 实现智能模式缓存
- 提供优化的架构查找和搜索
- 管理磁盘上的持久缓存
数据库上下文层
- 展示高级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存储库中创建问题

使用说明

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

目录

概述

特性

多数据库支持

用法

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

选项1：使用Docker（推荐）

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

在本地启动服务器

可用工具

get_table_schema

get_tables_schema

search_tables_schema

rebuild_schema_cache

get_database_vendor_info

search_columns

get_pl_sql_objects

get_object_source

get_table_constraints

get_table_indexes

get_dependent_objects

get_user_defined_types

get_related_tables

run_sql_query

建筑