@studious-xiaoyu/oracle-link

Oracle MCP Query Tool

一个基于 MCP（Model Context Protocol）的 Oracle 数据库“只读查询”服务器（Node.js/TypeScript），允许 MCP 客户端安全地执行 SELECT 查询。

功能特点

• 通过 MCP 协议与 AI 助手集成
• 仅执行 SELECT 查询获取数据（强制行数上限）
• 拒绝一切写操作（INSERT/UPDATE/DELETE 等）
• 安全的查询执行环境

安装与运行

依赖安装：

npm install

配置

在 src/config.ts 中直接填写数据库连接与默认行数：

export const oracleConfig = {
  username: 'your_username',
  password: 'your_password',
  connectString: 'localhost:1521/your_service_name',
  defaultMaxRows: 100
}

使用方法

开发模式（stdio）

npx -y tsx src/index.ts

作为 MCP 服务器运行（Node.js）

默认以 stdio 传输运行，便于在 Claude/Inspector 中作为命令接入；也可扩展为 HTTP 传输。

可用工具

oracle_query

执行 SELECT 查询并返回结果

参数:

• sql: 要执行的 SELECT 查询语句（允许 SELECT 或 WITH 开头）
• max_rows: 返回的最大行数（可选，默认 100；未限制时自动追加 FETCH FIRST {max_rows} ROWS ONLY）

oracle_list_tables

列出当前用户或指定 owner 的所有表名，并返回数量

参数:

• owner: 可选，指定 schema/owner 名（建议使用大写）

返回:

• success: 是否成功
• count: 表数量
• tables: 表名数组
• message: 文本信息

oracle_describe_table

查询指定表的详细元数据

参数:

• table_name: 表名（建议使用大写）
• owner: 可选，schema/owner 名（建议使用大写）

返回:

• success: 是否成功
• table: 表名
• comment: 表注释
• columns: 列定义（名称/类型/长度/精度/可空/默认/列注释）
• primaryKey: 主键列
• uniqueConstraints: 唯一约束及其列
• foreignKeys: 外键（约束名、列、引用的表和列）
• indexes: 索引（名称、唯一性、列）

开发

依赖

• Node.js 18+
• @modelcontextprotocol/sdk、zod、oracledb、dotenv

项目结构

oracle-link/
├── src/index.ts         # MCP 服务器入口（stdio）
├── src/oracle.ts        # Oracle 只读查询封装
├── package.json         # Node 项目配置与脚本
├── tsconfig.json        # TypeScript 配置
└── README.md            # 说明文档

注意事项

• 确保已安装/可用 Oracle 客户端库
• 确保网络连接和防火墙设置允许访问 Oracle 数据库
• 强烈建议在生产环境使用只读账号，仅授予查询权限

集成到 MCP 客户端

通用（npx 启动 stdio）

• 在你的 MCP 客户端里声明一个 stdio 服务器：

command: "npx"
args: ["-y", "@studious-xiaoyu/oracle-link"]
env:
  ORACLE_USERNAME: "scott"
  ORACLE_PASSWORD: "tiger"
  ORACLE_CONNECT_STRING: "localhost:1521/xe"
  DEFAULT_MAX_ROWS: "100"

Claude Desktop 配置示例（Windows/macOS）

• 在 claude_desktop_config.json 的 mcpServers 中添加：

{
  "mcpServers": {
    "oracle-link": {
      "command": "npx",
      "args": ["-y", "@studious-xiaoyu/oracle-link"],
      "env": {
        "ORACLE_USERNAME": "scott",
        "ORACLE_PASSWORD": "tiger",
        "ORACLE_CONNECT_STRING": "localhost:1521/xe",
        "DEFAULT_MAX_ROWS": "100"
      }
    }
  }
}

Cursor 设置示例

• 在 Cursor 的 MCP 设置中添加：

name: "oracle-link"
type: "stdio"
command: "npx"
args: ["-y", "@studious-xiaoyu/oracle-link"]
env:
  ORACLE_USERNAME: "scott"
  ORACLE_PASSWORD: "tiger"
  ORACLE_CONNECT_STRING: "localhost:1521/xe"

凭据传递方式

• 环境变量：通过 ORACLE_USERNAME、ORACLE_PASSWORD、ORACLE_CONNECT_STRING、ORACLE_PRIVILEGE（可选）提供连接信息。
• 工具级 URL：在调用工具时传入 url 覆盖连接，例如：
  • oracle://scott:tiger@localhost:1521/xe?maxRows=100
  • oracle://sys:sys_password@localhost:1521/xe?privilege=SYSDBA&maxRows=100

可用工具与输入

• oracle_query：sql、max_rows（默认 DEFAULT_MAX_ROWS）、url（可选）。
• oracle_list_tables：owner（可选）、url（可选）。
• oracle_describe_table：table_name、owner（可选）、url（可选）。

运行与排错

• 本地手动启动：npx -y @studious-xiaoyu/oracle-link 或 node dist/index.js。
• 如果客户端无法识别工具，检查：
  • 客户端是否支持 MCP stdio。
  • 环境变量是否设置正确。
  • 是否能连通 Oracle（端口、防火墙、权限）。