MCP-Oracle

Español | English

MCP（模型上下文协议）服务器，将 AI 代理连接到 Oracle 数据库。

它提供工具来浏览模式、读取 PL/SQL 源代码以及运行 SQL。它默认以只读模式启动；通过 ORACLE_ALLOW_WRITE=true 启用写入和存储过程调用。

它使用官方 Python SDK（mcp）和 python-oracledb。如果找到 Instant Client（或 ORACLE_HOME 的 lib/ 目录），则启用厚模式；否则使用薄模式。对于较旧的实例（10g/11g），其密码验证器在薄模式下不受支持，因此需要厚模式。

这个项目不是官方的 Oracle MCP 套件（oracle/mcp）。该仓库面向 Oracle Cloud 和其他 Oracle 产品。此服务器直接与您的数据库监听器通信。

工具

run_query 和 execute_dml 接受绑定变量（:name），因此您无需将值拼接到 SQL 中。

Related MCP server: Oracle DB MCP Server

要求

• Python 3.9+

• 可访问的 Oracle 实例（用户、密码、主机、端口和 service_name）

• 对于 Oracle 10g/11g（或薄模式失败时）：Oracle Instant Client 或 ORACLE_HOME 的 lib/ 目录

本地使用与生产环境

本 README 涵盖本地使用：Cursor 或 Claude Desktop 通过 stdio 在您的机器上启动 server.py（它不会打开 HTTP 端口）。

如果 MCP 需要在服务器上持续运行，并且客户端通过网络连接：

• Linux (RedHat)

• Windows Server

安装

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

复制环境模板并填写您的值：

cp .env.example .env

服务器不会自动加载 .env。这些变量必须通过 MCP 客户端配置（Cursor、Claude Desktop 等）传入。.env 文件仅作为本地参考；请勿提交它。

环境变量

厚模式与薄模式

启动时，服务器检查 ORACLE_CLIENT_LIB_DIR（或 ~/oracle/instantclient）。如果该文件夹存在，则调用 oracledb.init_oracle_client() 并使用厚模式。

示例：

# Instant Client (zip / RPM)
ORACLE_CLIENT_LIB_DIR=/Users/your_user/oracle/instantclient

# ORACLE_HOME 19c
ORACLE_CLIENT_LIB_DIR=/apps/oracle/product/19c/lib

如果没有原生客户端，则以薄模式运行（大多数情况下为 Oracle 12.1+）。

与 Cursor 一起使用

在 Cursor 中，将服务器添加到 MCP 配置（例如 ~/.cursor/mcp.json 或项目配置）：

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

使用 .venv Python 的绝对路径，以便客户端找到 mcp 和 oracledb。

重启 Cursor（或重新加载 MCP 服务器），并确认 oracle-mcp 出现在工具列表中。

与 Claude Desktop 一起使用

在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

手动运行

在本地，服务器通过 stdio 使用 MCP 通信（它不会打开 HTTP 端口）。在生产服务器上，传输方式为 HTTP；请参阅 本地使用与生产环境。

source .venv/bin/activate
export ORACLE_USER=my_user
export ORACLE_PASSWORD=my_password
export ORACLE_HOST=127.0.0.1
export ORACLE_PORT=1521
export ORACLE_SERVICE_NAME=ORCLPDB1
python server.py

如果没有 MCP 客户端连接到 stdin/stdout，您将不会看到交互式提示符；这是正常现象。

安全性

• 默认情况下 ORACLE_ALLOW_WRITE=false：execute_dml 和 call_procedure 会以 PermissionError 失败。

• run_query 拒绝以 INSERT、UPDATE、DELETE、MERGE、DROP、ALTER、TRUNCATE、CREATE、GRANT 或 REVOKE 开头的语句。

• execute_dml 仅接受 INSERT、UPDATE、DELETE 或 MERGE。

• 优先使用绑定变量（:id），而不是将值直接插入 SQL。

• 当您只需要浏览模式时，请使用最小权限用户连接。

• 请勿在版本化的 mcp.json 中提交 .env 或凭据。

依赖项

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0