cursor oracle MCP server

英语 | 中文

新项目：Cursor DB MCP

支持通过JDBC连接到任何数据库。\ 👉

______________________________________________________________________

Oracle MCP服务器

Oracle数据库的模型上下文协议（MCP）服务器，使Cursor等AI助手能够直接对Oracle数据库执行SQL语句。

刘 — https://alvinliu.com · 项目：

🎬 演示视频

👉 点击下面的图片在YouTube上观看 

特性

• 完全SQL支持：SELECT、INSERT、UPDATE、DELETE、DDL（CREATE、DROP、ALTER等）以及每个请求的多个语句
• 从文件执行：通过运行完整的SQL文件 execute_sql_file；尾随SQL\*Plus / 自动剥离
• 查询文件: query_to_csv_file （结果为CSV、RFC 4180、UTF-8）和 query_to_text_file （纯文本，制表符分隔，CLOB完整；例如用于程序源）
• PL/SQL块：CREATE PROCEDURE/FUNCTION/PACKAGE（包括带有前导注释的文件）和匿名块作为一个单元执行
• 人在循环审查UI：可配置的危险关键字会触发一个带有完整SQL的审查窗口。这 Keywords 区域显示了触发审核的实际扩展标识符（例如 created_at，不仅 create)
• 白名单审查旁路: Allow Header 将SQL第一行保存到 whitelist.json 并跳过未来对同一连接+标题行的审查
• 白名单关键字过滤: Allow Keyword 将关键字保存到 whitelist.json 未批准当前审查；未来的匹配只删除特定的扩展关键字触发器，而其他不匹配的危险触发器仍在审查中
• 白名单关键字护栏：review UI只接受由字母、数字和下划线组成的白名单关键字，并阻止完全匹配的值 danger_keywords 不区分大小写
• 危险关键字匹配: whole_text （完整SQL中的子字符串）或 tokens （精确的令牌匹配；例如。 created_at 不匹配 create)
• 多数据库：配置多个连接；使用 list_connections 查看名称和状态（在每个列表上重试失败的连接；仅 list_connections 重新验证——其他工具在不可用的连接上很快就会失败，直到您再次调用它）
• 审计日志：键入字段(AUDIT_TIME, AUDIT_CONNECTION, AUDIT_KEYWORDS, AUDIT_APPROVED, AUDIT_ACTION, AUDIT_SQL)加上白名单上下文，例如 HEADER_LINE 和 EXPANDED_KEYWORDS；完整SQL，记录分隔符 ######AUDIT_END######；10MB轮换，启动时重用最后一个非完整文件，文件名包括创建日期（例如。 audit_2006-01-02_150405.log)
• 连接安全：中的数据库连接字符串（包括密码） config.yaml 在首次启动时自动加密，无需手动步骤
• 跨平台审核UI：Windows（WinForms+WebBrowser）和macOS（JXA/Cocoa对话框）都支持 Allow Keyword, Allow Header, Execute，以及 Cancel
• 单个可执行文件：独立二进制文件（需要Oracle即时客户端）

需求

运行时依赖关系

1. Oracle即时客户端

- 下载自 Oracle网站 - 建议使用19c或更高版本 - 所需文件： oci.dll, oraociei19.dll （Windows）或同等产品 .dylib （macOS）

1. 环境设置

   # Windows: Add Instant Client to PATH
   set PATH=C:\path\to\instantclient;%PATH%

   # macOS: Set library path
   export DYLD_LIBRARY_PATH=/path/to/instantclient:$DYLD_LIBRARY_PATH

安装

下载预构建的二进制文件（推荐）

预构建的二进制文件发布在 。无需构建。

1. 下载 您平台的存档：

- 视窗: oracle-mcp-server-windows-amd64-.zip - macOS苹果硅（M1/M2/M3）: oracle-mcp-server-darwin-arm64-.tar.gz - macOS英特尔: oracle-mcp-server-darwin-amd64-.tar.gz

1. 提取 档案。您将获得：

- 可执行文件（例如。 oracle-mcp-server-windows-amd64.exe 或 oracle-mcp-server-darwin-arm64) - user_guide.md --逐步设置 - config.yaml.example --复制到 config.yaml 并编辑

1. 安装Oracle即时客户端 （参见 需求 上面）并将其添加到 PATH （Windows）或设置 ORACLE_HOME 和 DYLD_LIBRARY_PATH （macOS）。

1. 配置 config.yaml 使用数据库连接，然后将服务器添加到Cursor MCP（请参阅 配置 和 使用游标 在......下面

有关完整演练，请参见 user_guide.md.

配置

复制 config.yaml.example 到 config.yaml 并在以下配置至少一个连接 oracle.connections:

oracle:
  connections:
    database1: "user/pass@//host:1521/ORCL"
    # database2: "user/pass@//host2:1521/ORCL"

security:
  # "whole_text" = substring in full SQL; "tokens" = exact token match (e.g. created_at ≠ create)
  danger_keyword_match: "whole_text"

  danger_keywords:
    - truncate
    - drop
    - delete
    - create
    - update
    - execute immediate
    # ... (see config.yaml.example)

  require_confirm_for_ddl: true   # DDL always requires confirmation

logging:
  audit_log: true
  verbose_logging: true   # One short stderr line per execute_sql / execute_sql_file
  log_file: "audit.log"  # Base name; actual files: audit_YYYY-MM-DD_HHMMSS.log, 10MB rotation

随着 一 连接时，所有SQL都针对该数据库运行（无需传递 connection).随着 多个 连接，使用 connection 论点在 execute_sql / execute_sql_file 和 list_connections 查看名称和可用性。

连接安全： 首次启动时，中的任何纯文本连接字符串 config.yaml 被自动替换为加密值。文件已就地更新，注释和格式得以保留。

环境变量

带钱包的Oracle自主数据库（ADB）

亚洲开发银行使用 TCPS（SSL） 并要求 钱包.使用钱包中的TNS名称 tnsnames.ora （例如。 mcpdemo_high):

1. 下载钱包：Oracle云控制台→ 您的自主数据库→ DB连接 → 下载钱包.解压缩到文件夹（例如。 D:\oracle\wallet_mcpdemo).文件夹必须包含 tnsnames.ora, sqlnet.ora, cwallet.sso, ewallet.pem等等。
2. config.yaml --使用TNS别名和数据库用户/密码：

   oracle:
     connections:
       mcpdemo: "mcpdemo/YourPassword@mcpdemo_high"

1. 光标MCP --set TNS_ADMIN 到 钱包目录 因此，该过程可以找到 tnsnames.ora 以及SSL证书。在Windows上，还包括Instant Client PATH:

   {
     "mcpServers": {
       "oracle": {
         "command": "D:\\work\\code\\cursor_oracle_mcp_server\\oracle-mcp.exe",
         "args": [],
         "env": {
           "TNS_ADMIN": "D:\\oracle\\wallet_mcpdemo",
           "PATH": "C:\\path\\to\\instantclient;%PATH%"
         }
       }
     }
   }

替换 D:\oracle\wallet_mcpdemo 使用解压缩的钱包路径，并确保Instant Client已打开 PATH.没有 TNS_ADMIN，你可以看到 ORA-12541 （无侦听器）或SSL错误，因为客户端无法解析TNS名称或使用钱包。

使用游标

MCP配置

添加到光标MCP设置(~/.cursor/mcp.json 或工作空间 .cursor/mcp.json):

窗户：

Windows，将Oracle客户端添加到PATH

{
  "mcpServers": {
    "oracle": {
      "command": "C:\\path\\to\\oracle-mcp.exe",
      "args": []
    }
  }
}

苹果电脑

使用 env 块，以便MCP过程看到 ORACLE_HOME 和 DYLD_LIBRARY_PATH:

{
  "mcpServers": {
    "oracle": {
      "command": "/path/to/oracle-mcp",
      "args": [],
      "env": {
        "ORACLE_HOME": "/opt/oracle/instantclient_19_20",
        "DYLD_LIBRARY_PATH": "/opt/oracle/instantclient_19_20"
      }
    }
  }
}

替换 /path/to/oracle-mcp 和 /opt/oracle/instantclient_19_20 你的实际路径。您还可以引用现有的shell env "ORACLE_HOME": "${env:ORACLE_HOME}" 如果Cursor是从已设置的终端启动的。

工具

交互示例

// One connection: no need to pass connection
execute_sql({ "sql": "SELECT table_name FROM user_tables" })

// Multiple connections
execute_sql({ "sql": "SELECT * FROM my_table", "connection": "database1" })
execute_sql({ "sql": "CREATE TABLE test (id NUMBER)", "connection": "database2" })

// Run a SQL file (e.g. procedure script; trailing / stripped)
execute_sql_file({ "file_path": "d:\\scripts\\myscript.sql", "connection": "ps" })

// See connection names and status
list_connections()

// Write query result to CSV or text file (file_path must be absolute; same review rules as execute_sql when needed)
query_to_csv_file({ "sql": "SELECT * FROM my_table", "file_path": "d:\\out\\data.csv", "connection": "database1" })
query_to_text_file({ "sql": "SELECT text FROM user_source WHERE name='MY_PROC'", "file_path": "d:\\out\\my_proc.sql" })

安全和审查窗口

当SQL匹配时 danger_keywords 或者是DDL（如果 require_confirm_for_ddl 如果为真），将出现一个确认窗口：

• 关键词展示：review标头显示触发review的实际扩展标识符，而不仅仅是原始配置的危险关键字
• 允许标头：将当前SQL第一行存储在 whitelist.json；同一连接上具有相同第一行的未来SQL跳过审阅
• 允许关键字：在中存储一个关键字 whitelist.json 但确实如此 不 批准当前的审查；用户可以在选择之前添加多个关键字 Execute 或 Cancel
• 关键字白名单行为：白名单关键字仅删除特定的扩展关键字触发器；如果同一SQL仍然有其他危险的不匹配触发器，则仍然会打开查看
• 白名单存储: whitelist.json 存储在可执行目录/程序目录中
• 视窗：WinForms窗口，语法突出显示SQL（WebBrowser）
• macOS：JXA/Cocoa对话框，具有与Windows相同的审阅操作

只有在用户确认后才能执行。拒绝被记录并返回为 USER_REJECTED.

SQL执行

• 单一语句：一个SQL语句，后面有或没有分号。
• 多项声明：每行一个， 每行以分号结尾。按顺序执行。
• PL/SQL：创建程序/功能/包（包括带有前导的文件 -- 或 /* */)匿名块（BEGIN…END；/DDeclare…END；）被视为一个块，不被分割。
• 来自文件：跟踪SQL\*Plus / （在它自己的行上）在执行之前被删除。

审核日志

• 键控格式: AUDIT_TIME=..., AUDIT_CONNECTION=..., AUDIT_KEYWORDS=..., AUDIT_APPROVED=..., AUDIT_ACTION=...，可选 HEADER_LINE=...，可选 EXPANDED_KEYWORDS=...那么 AUDIT_SQL= 后面是完整的SQL，然后是一行 ######AUDIT_END###### 作为记录分隔符。
• 旋转：每个文件10MB。启动时，重用10MB以下的最新现有日志文件；当文件已满时，将创建一个新文件，其名称中包含创建日期： audit_2006-01-02_150405.log.

MCP协议

工具： execute_sql

输入: sql （必填）， connection （可选）。不要指定架构限定对象名称，例如 hr.employees；服务器拒绝了它们。

输出（查询）: columns, rows, statement_type, execution_time_ms, success.

输出（DML/DDL）: rows_affected, statement_type, execution_time_ms, success，可选 warning.

错误（用户拒绝）: code -32000, message “用户取消执行”， data.code “USER_REJECTED”， data.matched_keywords.

工具： execute_sql_file

输入: file_path （必填）， connection （可选）。分析和审查规则与 execute_sql；执行文件内容（尾随 / 剥离）。

工具： list_connections

输入：没有。 输出: connections （姓名+可用性）， message.只有此工具重新验证失败的连接；如果所选连接当前不可用，则其他工具会返回错误，直到您再次调用list_connections。

工具： query_to_csv_file

输入: sql （必填）， file_path （必需的绝对路径）， connection （可选）。 输出：成功与道路。确认规则与 execute_sql 当SQL匹配时 danger_keywords 或者是DDL（如果 require_confirm_for_ddl).写入带标头的CSV，UTF-8，RFC 4180；CLOB列已完整读取。

工具： query_to_text_file

输入: sql （必填）， file_path （必需的绝对路径）， connection （可选）。 输出：成功与道路。确认规则与 execute_sql 当SQL匹配时 danger_keywords 或者是DDL（如果 require_confirm_for_ddl).写入纯文本，制表符分隔列，无标题；完整的CLOB（例如用于程序源）。

故障排除

连接问题

Error: ORA-12541: TNS:no listener

→ 检查Oracle Instant Client是否在PATH中，侦听器是否正在运行

Error: DPI-1047: Cannot locate a 64-bit Oracle Client library

→ 安装Oracle即时客户端并添加到PATH

权限问题

Error: ORA-01031: insufficient privileges

→ 配置的数据库用户缺少所需的权限

从源构建（可选）

如果您更喜欢自己构建二进制文件（例如，用于不同的Go版本或平台）：

构建依赖关系

• 转到1.22+
• 必须启用CGO：godror需要CGO和C编译器。
• 视窗：使用 最小GW-w64 （GCC 7.2+）并添加其 bin 到PATH。

- 不要使用Cygwin的gcc。 如果两者都已安装，请确保MinGW bin 在PATH中位于Cygwin之前，或者您可能会看到 cannot parse gcc output ... as ELF, Mach-O, PE, XCOFF. - 通过Chocolatey安装： choco install mingw，或 Msys 2 然后 pacman -S mingw-w64-ucrt-x86_64-gcc 并使用 mingw64\bin. - 证实 where gcc 和 gcc -v；您应该看到“mingw”或“mingw”和64位（x86_64）。

• macOS：运行 xcode-select --install 用于命令行工具。

构建命令

重要：启用CGO并提供GCC进行构建，否则您将看到以下错误 undefined: VersionInfo.

# Clone the repository
git clone https://github.com/kjstart/cursor_oracle_mcp_server
cd cursor_oracle_mcp_server

# Download dependencies
go mod tidy

# Windows (PowerShell): enable CGO and ensure gcc is in PATH
$env:CGO_ENABLED="1"
go build -o oracle-mcp.exe .

# Windows (CMD)
set CGO_ENABLED=1
go build -o oracle-mcp.exe .

# Windows (MSYS UCRT64)
export PATH=/c/oracle/instantclient_21_12:$PATH
export ORACLE_HOME=/c/oracle/instantclient_21_12
pacman -S mingw-w64-ucrt-x86_64-go
export GOROOT=/ucrt64/lib/go
export PATH=$GOROOT/bin:$PATH
export CGO_ENABLED=1
export CC=x86_64-w64-mingw32-gcc
go install github.com/godror/godror@latest
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 go build -o oracle-mcp.exe .

# macOS (Intel): native build only
CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o oracle-mcp .

# macOS (Apple Silicon)
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o oracle-mcp .

构建故障排除

更改gcc或PATH后，清除构建缓存并重新构建：

go clean -cache
go build -o oracle-mcp.exe .

许可证

MIT许可证-请参阅 许可证 文件

贡献

1. 分叉存储库
2. 创建要素分支
3. 提交拉取请求

致谢

• 上帝 -Go的Oracle驱动程序
• 模型上下文协议 -MCP规范

______________________________________________________________________

英语 | 中文

新项目 Cursor DB MCP 可以连接到各种数据库产品(包括OceanBase等信创数据库)

👉

______________________________________________________________________

Oracle MCP Server（中文）

基于 Model Context Protocol (MCP) 的 Oracle 数据库服务端，让 Cursor 等 AI 助手直接对 Oracle 数据库执行 SQL。

作者：Alvin Liu — https://alvinliu.com · 项目：

B站视频介绍: Cursor连接Oracle自动编写存储过程

功能

• 完整 SQL 支持：SELECT、INSERT、UPDATE、DELETE、DDL（CREATE、DROP、ALTER 等），单次请求可执行多条语句
• 从文件执行：通过 execute_sql_file 执行整个 SQL 文件；自动去除末尾 SQL\*Plus 的 /
• 查询结果写入文件：query_to_csv_file（结果写为 CSV，RFC 4180，UTF-8）与 query_to_text_file（纯文本、制表符分隔、CLOB 完整输出，如存过程源码）
• PL/SQL 块：CREATE PROCEDURE/FUNCTION/PACKAGE（含文件头部注释）及匿名块作为整体执行
• 人工确认窗口：可配置危险关键词，触发带完整 SQL 的确认窗口；Keywords 区域显示的是真正命中的 expanded keyword（例如显示 created_at，而不是只显示 create）
• Header 白名单：Allow Header 会把 SQL 第一行写入 whitelist.json，下次同一连接且第一行相同的 SQL 直接跳过 review
• Keyword 白名单：Allow Keyword 只把关键字写入 whitelist.json，不会自动批准当前 review；后续只会消掉该 expanded keyword 对应的触发项，其他未放行触发项仍会继续弹出 review
• Keyword 白名单限制：只能添加字母、数字、下划线组成的关键字；如果与 danger_keywords 中某项完全相同（忽略大小写）则禁止添加
• 危险词匹配：whole_text（整段 SQL 子串）或 tokens（精确词匹配，如 created_at 不匹配 create）
• 多数据库：可配置多个连接；用 list_connections 查看名称与状态（失败连接每次列出时会重试；仅 list_connections 会重新校验—其他工具在连接不可用时直接报错，需再次调用 list_connections 后重试）
• 审计日志：键值字段（AUDIT_TIME、AUDIT_CONNECTION、AUDIT_KEYWORDS、AUDIT_APPROVED、AUDIT_ACTION、AUDIT_SQL），并可附带 HEADER_LINE、EXPANDED_KEYWORDS；完整 SQL、记录分隔符 ######AUDIT_END######；单文件 10MB 轮转，启动时复用最近未满的日志，文件名含创建日期（如 audit_2006-01-02_150405.log）
• 连接安全：config.yaml 中的数据库连接串（含密码）在首次启动时自动加密，无需任何手动操作
• 跨平台确认窗口：Windows（WinForms + WebBrowser）与 macOS（JXA/Cocoa）都支持 Allow Keyword、Allow Header、Execute、Cancel
• 单可执行文件：独立二进制（需安装 Oracle Instant Client）

环境要求

运行时依赖

1. Oracle即时客户端

- 从 Oracle 官网 下载 - 建议 19c 或更高版本 - 所需文件：oci.dll、oraociei19.dll（Windows）或对应 .dylib（macOS）

1. 环境配置

   # Windows：将 Instant Client 加入 PATH
   set PATH=C:\path\to\instantclient;%PATH%

   # macOS：设置库路径
   export DYLD_LIBRARY_PATH=/path/to/instantclient:$DYLD_LIBRARY_PATH

安装

下载预编译包（推荐）

预编译包发布在 ，无需自行编译。

1. 下载对应平台的压缩包：

- 视窗：oracle-mcp-server-windows-amd64-.zip - macOS苹果硅（M1/M2/M3）：oracle-mcp-server-darwin-arm64-.tar.gz - macOS英特尔：oracle-mcp-server-darwin-amd64-.tar.gz

1. 解压后得到：

- 可执行文件（如 oracle-mcp-server-windows-amd64.exe 或 oracle-mcp-server-darwin-arm64） - user_guide.md — 分步设置说明 - config.yaml.example — 复制为 config.yaml 后编辑

1. 安装 Oracle Instant Client（见上方 环境要求），并加入 PATH（Windows）或设置 ORACLE_HOME、DYLD_LIBRARY_PATH（macOS）

1. 配置 config.yaml 中的数据库连接，再将本服务加入 Cursor MCP（见下方 配置 与 在 Cursor 中使用）。

完整步骤可参考 user_guide.md。

配置

将 config.yaml.example 复制为 config.yaml，在 oracle.connections 下至少配置一个连接：

oracle:
  connections:
    database1: "user/pass@//host:1521/ORCL"
    # database2: "user/pass@//host2:1521/ORCL"

security:
  # danger_keywords 匹配方式："whole_text" 或 "tokens"
  danger_keyword_match: "whole_text"

  danger_keywords:
    - truncate
    - drop
    - delete
    - create
    - update
    - execute immediate
    # ... (见 config.yaml.example)

  require_confirm_for_ddl: true   # DDL 始终需确认

logging:
  audit_log: true
  verbose_logging: true
  log_file: "audit.log"

单连接时所有 SQL 都发往该库（无需传 connection）。多连接时在 execute_sql / execute_sql_file 中通过 connection 指定，并用 list_connections 查看名称与可用性。

连接安全： 首次启动时，config.yaml 中的明文连接串会被自动替换为加密值，文件原地更新，注释与格式完整保留。

环境变量

Oracle 自治数据库 (ADB) 与 Wallet

ADB 使用 TCPS（SSL），需要 钱包。连接串使用钱包中 tnsnames.ora 的 TNS 别名（如 mcpdemo_high）：

1. 下载 Wallet：Oracle Cloud 控制台 → 你的自治数据库 → DB 连接 → 下载 Wallet。解压到某目录（如 D:\oracle\wallet_mcpdemo），该目录需包含 tnsnames.ora、sqlnet.ora、cwallet.sso、ewallet.pem 等。
2. config.yaml — 使用 TNS 别名和数据库用户/密码：

   oracle:
     connections:
       mcpdemo: "mcpdemo/YourPassword@mcpdemo_high"

1. 光标MCP — 在 MCP 配置中设置 TNS_ADMIN 为 Wallet 目录，以便进程找到 tnsnames.ora 和 SSL 证书。Windows 下还需在 PATH 中包含 Instant Client：

   {
     "mcpServers": {
       "oracle": {
         "command": "D:\\path\\to\\oracle-mcp-server-windows-amd64.exe",
         "args": [],
         "env": {
           "TNS_ADMIN": "D:\\oracle\\wallet_mcpdemo",
           "PATH": "C:\\path\\to\\instantclient;%PATH%"
         }
       }
     }
   }

将 D:\oracle\wallet_mcpdemo 换成你的 Wallet 解压路径，并确保 Instant Client 在 PATH 中。未设置 TNS_ADMIN 可能出现 ORA-12541（无监听）或 SSL 相关错误。

在 Cursor 中使用

MCP 配置

在 Cursor 的 MCP 设置（~/.cursor/mcp.json 或工作区 .cursor/mcp.json）中添加：

Windows（Oracle 客户端已在系统 PATH 中）：

{
  "mcpServers": {
    "oracle": {
      "command": "C:\\path\\to\\oracle-mcp-server-windows-amd64.exe",
      "args": []
    }
  }
}

macOS

通过 env 让 MCP 进程能读到 ORACLE_HOME 和 DYLD_LIBRARY_PATH：

{
  "mcpServers": {
    "oracle": {
      "command": "/path/to/oracle-mcp-server-darwin-arm64",
      "args": [],
      "env": {
        "ORACLE_HOME": "/opt/oracle/instantclient_19_20",
        "DYLD_LIBRARY_PATH": "/opt/oracle/instantclient_19_20"
      }
    }
  }
}

将 /path/to/oracle-mcp-server-darwin-arm64 和 /opt/oracle/instantclient_19_20 换成你的实际路径。若从已设置环境的终端启动 Cursor，也可用 "ORACLE_HOME": "${env:ORACLE_HOME}" 引用现有环境变量。

工具说明

使用示例

// 单连接：无需传 connection
execute_sql({ "sql": "SELECT table_name FROM user_tables" })

// 多连接
execute_sql({ "sql": "SELECT * FROM my_table", "connection": "database1" })
execute_sql({ "sql": "CREATE TABLE test (id NUMBER)", "connection": "database2" })

// 执行 SQL 文件（末尾 / 会被去除）
execute_sql_file({ "file_path": "d:\\scripts\\myscript.sql", "connection": "ps" })

// 查看连接名称与状态
list_connections()

// 将查询结果写入 CSV 或文本文件（file_path 须为绝对路径；需要时与 execute_sql 相同审查规则）
query_to_csv_file({ "sql": "SELECT * FROM my_table", "file_path": "d:\\out\\data.csv", "connection": "database1" })
query_to_text_file({ "sql": "SELECT text FROM user_source WHERE name='MY_PROC'", "file_path": "d:\\out\\my_proc.sql" })

安全与确认窗口

当 SQL 命中 danger_keywords 或为 DDL（且 require_confirm_for_ddl 为 true）时，会弹出确认窗口：

• 关键词展示：窗口中的 Keywords 显示真正命中的 expanded keyword，而不是原始 danger keyword
• 允许标头：把当前 SQL 第一行写入 whitelist.json；同一连接下第一行再次匹配时直接跳过 review
• 允许关键字：只写入一个 keyword 到 whitelist.json，不会批准当前 review；可以在同一个窗口里连续添加多个 keyword
• Keyword 白名单行为：某个 keyword 被放行后，只会消掉它自己对应的 expanded keyword 触发项；如果 SQL 里还有其他未放行危险项，仍然会弹出 review
• 白名单位置：whitelist.json 位于程序目录 / 可执行文件目录
• 视窗：WinForms 窗口，SQL 语法高亮（WebBrowser）
• macOS：JXA/Cocoa 窗口，交互语义与 Windows 一致

用户确认后才会执行。拒绝会记录并返回 USER_REJECTED。

SQL 执行规则

• 单条语句：一条 SQL，可有可无末尾分号。
• 多条语句：每行一条，每行以分号结尾。按顺序执行。
• PL/SQL：CREATE PROCEDURE/FUNCTION/PACKAGE（含文件头部 -- 或 /* */）及匿名块（BEGIN...END; / DECLARE...END;）视为一整块，不拆分。
• 从文件：单独一行的 SQL\*Plus / 会在执行前移除。

审计日志

• 键值格式：AUDIT_TIME=...、AUDIT_CONNECTION=...、AUDIT_KEYWORDS=...、AUDIT_APPROVED=...、AUDIT_ACTION=...，以及可选的 HEADER_LINE=...、EXPANDED_KEYWORDS=...，然后是 AUDIT_SQL= 后跟完整 SQL，再以 ######AUDIT_END###### 作为记录分隔。
• 轮转：单文件 10MB。启动时复用最近未满的日志文件；写满后新建带创建日期的文件，如 audit_2006-01-02_150405.log。

MCP 协议

工具：execute_sql

输入：sql（必填），connection（可选）。

输出（查询）：columns、rows、statement_type、execution_time_ms、success。

输出（DML/DDL）：rows_affected、statement_type、execution_time_ms、success，可选 warning。

错误（用户拒绝）：code -32000，message “用户取消执行”data.code “USER_REJECTED”data.matched_keywords。

工具：execute_sql_file

输入：file_path（必填），connection（可选）。与 execute_sql 相同的分析与确认规则；执行文件内容（末尾 / 去除）。

工具：list_connections

输入：无。输出：connections（名称 + 可用性），message。仅此工具会重新校验失败连接；其他工具在所选连接不可用时直接报错，需再次调用 list_connections 后重试。

工具：query_to_csv_file

输入：sql（必填）、file_path（必填，绝对路径）、connection（可选）。输出：成功及路径。与 execute_sql 相同：命中 danger_keywords 或为 DDL（若 require_confirm_for_ddl）时弹出确认。写入带表头的 CSV，UTF-8，RFC 4180；CLOB 列完整读取。

工具：query_to_text_file

输入：sql（必填）、file_path（必填，绝对路径）、connection（可选）。输出：成功及路径。与 execute_sql 相同：命中 danger_keywords 或为 DDL（若 require_confirm_for_ddl）时弹出确认。写入纯文本，列以制表符分隔、无表头；CLOB 完整输出（如存过程源码）。

故障排除

连接问题

Error: ORA-12541: TNS:no listener

→ 确认 Oracle Instant Client 在 PATH 中且监听正常

Error: DPI-1047: Cannot locate a 64-bit Oracle Client library

→ 安装 Oracle Instant Client 并加入 PATH

权限问题

Error: ORA-01031: insufficient privileges

→ 当前配置的数据库用户权限不足

从源码构建（可选）

若希望自行编译（例如使用不同 Go 版本或平台）：

构建依赖

• 转到1.22+
• 须启用 CGO：godror 依赖 CGO 和 C 编译器。
• 视窗：使用 最小GW-w64（GCC 7.2+）并将其 bin 加入 PATH。

- 不要用 Cygwin 的 gcc。 若两者都有，确保 PATH 中 MinGW 的 bin 在 Cygwin 之前，否则可能出现 cannot parse gcc output ... as ELF, Mach-O, PE, XCOFF。 - 可用 Chocolatey：choco install mingw，或 Msys 2 后 pacman -S mingw-w64-ucrt-x86_64-gcc，使用 mingw64\bin。 - 用 where gcc 和 gcc -v 检查，应看到 "mingw" 或 "MinGW" 及 64 位 (x86_64)。

• macOS：执行 xcode-select --install 安装命令行工具。

构建命令

注意：需在启用 CGO 且已安装 GCC 的环境下构建，否则会出现 undefined: VersionInfo 等错误。

# 克隆仓库
git clone https://github.com/kjstart/cursor_oracle_mcp_server
cd cursor_oracle_mcp_server

# 下载依赖
go mod tidy

# Windows (PowerShell)：启用 CGO，确保 gcc 在 PATH 中
$env:CGO_ENABLED="1"
go build -o oracle-mcp.exe .

# Windows (CMD)
set CGO_ENABLED=1
go build -o oracle-mcp.exe .

# macOS (Intel)
CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o oracle-mcp .

# macOS (Apple Silicon)
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o oracle-mcp .

构建故障排除

修改 gcc 或 PATH 后，清理缓存再构建：

go clean -cache
go build -o oracle-mcp.exe .

许可证

MIT License - 见 许可证 文件

参与贡献

1. Fork 本仓库
2. 创建功能分支
3. 提交 Pull Request

致谢

• 上帝 - Go 版 Oracle 驱动
• 模型上下文协议 - MCP 规范