de en es ja ko ru zh

oracle-mcp

Name: oracle-mcp
Author: sharat9703

by sharat9703

Overview Schema Related Servers Score Discussions

TypeScript

Local

oracle-mcp

一个面向 Model Context Protocol 的只读 Oracle 数据库服务器。它让 AI 代理（Claude Desktop、Claude Code、Cursor、VS Code 代理、OpenAI Agents 等）能够安全地检查大型遗留 Oracle 模式——数千张表、数百个包、视图、同义词、触发器、序列和 PL/SQL 源码——而绝不修改数据。

它被设计为一个独立模块，与现有的"工程 MCP"（GitLab / Redmine / Taiga / ERPNext）并行运行：一个代理，多个 MCP 服务器。

安全模型一句话总结： 服务器只发出 SELECT 和数据字典读取，每个对象名都作为绑定变量传递，自由格式 SQL 由故障关闭式只读守卫检查，数据库账户本身应被授予只读权限。纵深防御，而非单一闸门。

功能特性

24 个聚焦工具，涵盖搜索、描述、DDL、源码、依赖、索引、约束、触发器、同义词、统计信息、无效对象以及受守卫保护的 SELECT 执行。
构造上即只读——SQL 守卫拒绝除单一、无注释的 SELECT / WITH … SELECT 之外的一切。
处处使用绑定变量——对象名和关键字从不拼接进 SQL。
有界且安全——硬性行数上限（默认 1000）、每条语句超时、ResultSet 清理。
连接池，支持透明重连（thick 模式 / Oracle Instant Client）。
结构化日志输出到 stderr（时间戳、工具、耗时、行数、模式、SQL）——绝不记录机密。
类型化错误分类——连接 / 校验 / 非法 SQL / 权限 / 未找到 / 超时 / oracle。
强类型（TypeScript strict）且经过测试（守卫与辅助函数共 48 个单元测试）。

环境要求

Node.js ≥ 18
已安装 Oracle Instant Client 并在库路径上（此构建使用 oracledb thick 模式）。
- Windows：Instant Client 文件夹位于 PATH 上。
- Linux/macOS：位于 LD_LIBRARY_PATH / DYLD_LIBRARY_PATH 上，或设置 ORACLE_CLIENT_LIB_DIR。
可访问数据库的网络连接，以及一个只读 Oracle 账户（参见安全）。

安装

git clone <your-repo>/oracle-mcp.git
cd oracle-mcp
npm install
npm run build          # compiles src/ → dist/

无需数据库即可验证：

npm test               # 48 unit tests (SQL guard, identifiers, formatting)

针对真实数据库（只读）进行冒烟测试：

ORACLE_USER=... ORACLE_PASSWORD=... ORACLE_CONNECT_STRING=host:port/service \
  npx tsx scripts/integration-check.ts

配置

通过环境变量进行配置。服务器会自动从其自身包目录加载 .env 文件（复制 .env.example → .env），因此机密信息存放在服务器旁边，远离你的代理配置。配置在启动时校验；如有缺失，服务器会快速失败并给出可读的、 不含机密的消息。

数据库（一个或多个）

服务器可以同时检查多个 Oracle 数据库。每个工具都接受可选的 database 参数；省略时使用默认数据库。

单数据库：

ORACLE_USER="readonly_user"
ORACLE_PASSWORD="change_me"
ORACLE_CONNECT_STRING="host:port/service"

多数据库——列出名称，然后以 ORACLE_<NAME>_ 前缀提供每个名称对应的变量（名称大写，非字母数字字符 → _）：

ORACLE_DATABASES=tcil,sbi_eforex,ybl
ORACLE_DEFAULT_DATABASE=tcil
ORACLE_TCIL_USER="…"        ORACLE_TCIL_PASSWORD="…"        ORACLE_TCIL_CONNECT_STRING="host:port/service"
ORACLE_SBI_EFOREX_USER="…"  ORACLE_SBI_EFOREX_PASSWORD="…"  ORACLE_SBI_EFOREX_CONNECT_STRING="host:port/service"
ORACLE_YBL_USER="…"         ORACLE_YBL_PASSWORD="…"         ORACLE_YBL_CONNECT_STRING="host:port/service"

连接池按数据库惰性创建——配置十个数据库在查询之前不产生任何开销。用双引号包裹密码，使 $/# 被按字面处理。

连接字符串提示： 对于 PDB，请使用服务名形式 host:port/service。较旧的 host:port:SID 形式不是 Easy Connect——请转换（…:port/service）或使用 tnsnames 别名。

共享设置

变量	默认值	描述
`ORACLE_CLIENT_LIB_DIR`	(来自 PATH)	Instant Client 目录。若未设置，通过 PATH/LD_LIBRARY_PATH 发现。
`ORACLE_TNS_ADMIN`	—	包含 `tnsnames.ora`/`sqlnet.ora` 的目录（如使用）。
`ORACLE_MAX_ROWS`	`1000`	任何工具返回行数的硬性上限（也是调用方可请求的最大值）。
`ORACLE_QUERY_TIMEOUT_MS`	`15000`	每条语句的超时时间（thick 模式 `callTimeout`）。
`ORACLE_POOL_MIN` / `_MAX` / `_INCREMENT`	`1` / `4` / `1`	连接池大小（按数据库）。
`ORACLE_POOL_TIMEOUT`	`60`	空闲连接修剪（秒）。
`ORACLE_DEFAULT_SCHEMA`	—	当省略 `schema` 时，owner 作用域工具的默认属主。
`LOG_LEVEL`	`info`	`error` \| `warn` \| `info` \| `debug`（日志 → stderr）。

接入代理

oracle-mcp 通过 stdio 使用 MCP 协议。将它放在你的工程 MCP 旁边。

Claude Desktop / Claude Code（claude_desktop_config.json / .mcp.json）——此处无机密；服务器读取自己的 .env：

{
  "mcpServers": {
    "engineering": { "command": "node", "args": ["/path/to/mcp-erpnext/src/index.js"] },
    "oracle": {
      "command": "node",
      "args": ["/path/to/oracle-mcp/dist/index.js"],
      "cwd": "/path/to/oracle-mcp"
    }
  }
}

凭据存放在 oracle-mcp/.env（已 gitignore）中，而非代理配置中。将 Oracle 放在独立服务器中（而不是合并到 JS 工程 MCP 中），可以隔离安全关键的数据库面，并允许你独立授权/部署。

架构

                        ┌──────────────────────────────────────────────┐
   AI agent  ──stdio──▶ │  index.ts  (McpServer, StdioServerTransport)  │
   (Claude/Cursor/…)    └───────────────┬──────────────────────────────┘
                                        │ registers 24 tools
                        ┌───────────────▼───────────────┐
                        │  tools/oracle/*                │  runSelect · executionPlan · ddl
                        │  (thin handlers, zod schemas)  │  · 20 declarative metadata tools
                        └───────┬───────────────┬────────┘
              guarded SQL       │               │  built SQL + binds
                    ┌───────────▼──────┐   ┌─────▼─────────────────────┐
                    │ validation/      │   │ oracle/client.ts          │
                    │ sqlGuard.ts      │   │  • timeout (callTimeout)  │
                    │ (fail-closed)    │   │  • row cap + truncation   │
                    └──────────────────┘   │  • ResultSet cleanup      │
                                           │  • error → taxonomy       │
                                           └─────┬─────────────────────┘
                                                 │ pooled connection
                                           ┌─────▼───────────────┐
                                           │ oracle/pool.ts       │  thick init · pool · reconnect
                                           └─────┬───────────────┘
                                                 ▼
                                        Oracle DB  (ALL_* dictionary + DBMS_METADATA/DBMS_XPLAN)

  cross-cutting:  config/env.ts (zod-validated)   logging/logger.ts (stderr, redacted)
                  errors.ts (typed taxonomy)       utils/ (identifiers, formatting)

文件夹结构

oracle-mcp/
├── src/
│   ├── index.ts               # server bootstrap + graceful shutdown
│   ├── config/env.ts          # env loading & validation (zod)
│   ├── logging/logger.ts      # structured stderr logger (+ SQL redaction)
│   ├── errors.ts              # OracleMcpError + Oracle→taxonomy mapping
│   ├── types/index.ts         # shared types
│   ├── validation/sqlGuard.ts # read-only SQL guard  ◀── security core
│   ├── utils/
│   │   ├── identifiers.ts      # name validation, LIKE-pattern escaping
│   │   └── format.ts           # Markdown tables / code blocks
│   ├── oracle/
│   │   ├── pool.ts             # thick init, pool lifecycle, reconnect
│   │   └── client.ts           # the single query choke-point
│   └── tools/oracle/
│       ├── context.ts          # tool type + registration wrapper
│       ├── runSelect.ts        # oracle_run_select (guarded)
│       ├── executionPlan.ts    # oracle_show_execution_plan
│       ├── ddl.ts              # oracle_get_object_ddl / oracle_get_view
│       ├── metadataTools.ts    # 20 declarative dictionary tools
│       └── index.ts            # catalogue + registerOracleTools()
├── tests/                     # vitest unit tests
├── scripts/integration-check.ts
└── .env.example

为何做这些选择

独立 TS 包，而非合并到 JS 工程 MCP——隔离安全敏感面，允许严格类型构建和独立部署/授权。
Thick 模式——为此部署选择（存在 Instant Client）；启用最广泛的驱动功能集。如需要，Thin 模式可移除客户端依赖。
声明式元数据工具——20 个字典工具共享一种安全形态（固定 SQL + 绑定 + 格式），因此添加一个工具只需几行，且安全属性统一。
单一 OracleClient 汇聚点——每个查询都流经它，因此超时、行数上限、清理、错误映射和日志记录在恰好一个位置强制执行。

工具参考

所有工具均以 oracle_ 为前缀。owner 作用域工具接受可选的 schema；搜索工具接受可选的 limit（限制在 ORACLE_MAX_ROWS 内）。名称可写为 OBJECT 或 SCHEMA.OBJECT。

工具	关键参数	用途
`oracle_run_select`	`sql`, `maxRows?`	执行受守卫保护的只读 SELECT。
`oracle_show_execution_plan`	`sql`	对 SELECT 执行 EXPLAIN PLAN + DBMS_XPLAN（不触碰数据）。
`oracle_list_schemas`	—	列出账户可见的属主/模式。
`oracle_list_tables`	`schema?`, `keyword?`, `limit?`	列出表（可选过滤）。
`oracle_search_tables`	`keyword`	名称包含关键字的表。
`oracle_find_table`	`table_name`	跨模式定位表，包括同义词。
`oracle_describe_table`	`table_name`, `schema?`	列 + 类型 + 可空性 + 注释。
`oracle_search_columns`	`column_name`	名称包含关键字的列（例如 `RISK`）。
`oracle_find_column`	`column_name`	拥有某列的表（精确匹配优先）。
`oracle_get_indexes`	`table_name`	索引及其列、唯一性、类型、状态。
`oracle_get_constraints`	`table_name`	PK/FK/UK/CHECK 及其列、引用表、删除规则。
`oracle_find_triggers`	`table_name`	表上的触发器（时机、事件、状态）。
`oracle_get_object_ddl`	`object_name`, `object_type?`	通过 `DBMS_METADATA` 获取完整 CREATE DDL。
`oracle_get_view`	`view_name`	视图 DDL + 列清单。
`oracle_get_package_source`	`package_name`	包规范源码。
`oracle_get_package_body`	`package_name`	包主体源码。
`oracle_search_package`	`package_name`	按名称关键字查找包。
`oracle_search_procedure`	`procedure_name`	查找过程/函数（独立及包内）。
`oracle_search_source`	`keyword`, `object_type?`	所有 PL/SQL 源码的全文搜索——引用与调用方。
`oracle_find_dependencies`	`object_name`, `direction?`	`used_by`（调用方）或 `uses`（被引用对象）。
`oracle_list_synonyms`	`schema?`, `keyword?`, `target_table?`	同义词；`target_table` → "指向"。
`oracle_get_table_statistics`	`table_name`	行数、块数、平均行长、最后分析时间。
`oracle_list_invalid_objects`	`schema?`	处于 `INVALID` 状态的对象。
`oracle_describe_object`	`object_name`	对象是什么（类型/属主/状态），来自 `ALL_OBJECTS`。

常见问题如何映射到工具

问题	工具
`MFX_GET_MARGIN` 在哪里定义？	`oracle_search_procedure` → `oracle_describe_object`
显示包主体	`oracle_get_package_body`
查找所有调用 `MFX_GET_MARGIN` 的过程	`oracle_find_dependencies`（`used_by`）或 `oracle_search_source`
所有对 `mfx_transaction` 的引用	`oracle_search_source`
描述 `mfx_entity_master`	`oracle_describe_table`
包含 "risk" 的列	`oracle_search_columns`
表上的索引 / 外键 / 触发器	`oracle_get_indexes` / `oracle_get_constraints` / `oracle_find_triggers`
解释此查询	`oracle_show_execution_plan`
指向某表的同义词	`oracle_list_synonyms`（`target_table`）
无效对象	`oracle_list_invalid_objects`

安全考虑

分层（纵深防御）：

只读账户（第一道防线）。 只为连接用户授予 CREATE SESSION + SELECT（针对其必须检查的对象或角色），并为连接用户授予用于数据字典的 SELECT_CATALOG_ROLE。MCP 应无法执行任何写入操作，无论其上层存在任何 bug。
SQL 守卫（validation/sqlGuard.ts）针对唯一的自由格式工具（oracle_run_select）——它采用**默认拒绝（fail closed）**策略，并拒绝以下内容：
- 任何不是单个 SELECT / WITH … SELECT 语句的内容；
- INSERT/UPDATE/DELETE/MERGE/…、所有 DDL、GRANT/REVOKE、COMMIT/ROLLBACK；
- PL/SQL 块（BEGIN/DECLARE）、CALL、EXECUTE [IMMEDIATE]、SELECT … INTO、FOR UPDATE；
- 危险包（DBMS_SQL、DBMS_SCHEDULER、DBMS_JOB、UTL_FILE、UTL_HTTP、…）；
- 分号 / 多条语句，以及所有注释/提示（一种经典的绕过手段）；
- 它会分析一个仅代码的投影，其中字符串字面量的内容已被清空，因此隐藏在字面量中的关键字或分号既不会误触发，也无法夹带第二条语句。
绑定变量——23 个元数据工具中的每个对象名/关键字都使用绑定变量；用户输入是值，绝不是 SQL 文本。标识符还会根据严格的字符集进行额外校验。
边界限制——硬性行数上限（ORACLE_MAX_ROWS）、每条语句的 callTimeout、ResultSet 清理。
不泄露机密——密码永远不会被记录到日志；日志仅输出到 stderr（stdout 是 MCP 通道）；日志中的 SQL 设有长度上限。

说明

oracle_show_execution_plan 运行 EXPLAIN PLAN，它会写入会话私有的全局临时表 PLAN_TABLE。这只是临时元数据，会自动丢弃，而且只读账户也可以使用——不会读取或写入任何生产数据。
该守卫有意设计得非常严格；如果存在专用的元数据工具，请优先使用它，而不是 oracle_run_select。极少数误报（例如某列恰好以非保留关键字命名）可以通过别名绕过。

示例

Agent: "Describe mfx_entity_master."
 → oracle_describe_table { table_name: "MFX_ENTITY_MASTER" }

Agent: "Find every procedure that references mfx_transaction."
 → oracle_search_source { keyword: "mfx_transaction", object_type: "PACKAGE BODY" }

Agent: "Show the body of MFX_GET_MARGIN."
 → oracle_get_package_body { package_name: "MFX_GET_MARGIN" }

Agent: "What foreign keys does mfx_transaction have?"
 → oracle_get_constraints { table_name: "MFX_TRANSACTION" }

Agent: "Explain: SELECT * FROM mfx_transaction WHERE trans_date > SYSDATE - 7"
 → oracle_show_execution_plan { sql: "SELECT * FROM mfx_transaction WHERE trans_date > SYSDATE - 7" }

测试

npm test            # unit: SQL guard (accept/reject matrix), identifiers, LIKE escaping
npm run typecheck   # tsc --noEmit
npx tsx scripts/integration-check.ts   # live smoke test (needs a DB; read-only)

单元测试特意聚焦于安全守卫——即接受集（SELECT/CTE、包含禁用词的字面量、转义引号、近似关键字的标识符）和拒绝集（DML/DDL、分号、注释/提示、PL/SQL、危险包、q'…'、超长、非字符串）。

故障排查

症状	原因 / 修复
`DPI-1047: Cannot locate a 64-bit Oracle Client library`	未找到 Instant Client。请安装它并将其加入 `PATH`/`LD_LIBRARY_PATH`，或设置 `ORACLE_CLIENT_LIB_DIR`。
`ORA-12154 / ORA-12541 / ORA-12514`	连接字符串错误 / 无监听器 / 未知服务。请使用 `host:port/service`（服务名，而非 SID）或有效的 tnsnames 别名。
`ORA-01017: invalid username/password`	`ORACLE_USER`/`ORACLE_PASSWORD` 错误。
`[PERMISSION_DENIED] ORA-01031` 或数据字典结果为空	该账户缺少对对象的 `SELECT` 权限或 `SELECT_CATALOG_ROLE` 角色。请授予读取访问权限。
`[VALIDATION_FAILURE] Only SELECT … permitted`	SQL 不是单独的 SELECT（或包含分号/注释）。请发送一条干净的 SELECT 语句。
工具返回的行涉及多个 schema	该对象名存在于多个可见的 schema 中。请传入 `schema`（或设置 `ORACLE_DEFAULT_SCHEMA`）以限定范围。
智能体看不到输出，但 stderr 中有日志	正确——按设计，日志只写入 stderr；stdout 仅承载 MCP 协议。
服务器启动后立即退出	查看 stderr 中的输出——配置校验会准确指出是哪个环境变量出错（不包含任何机密）。

许可证

MIT。

This server cannot be installed

license - permissive license

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

Oracle DB MCP Server
Databases Developer Tools
titan213
A
license
A
quality
C
maintenance
Enables AI tools to interact with Oracle databases through query execution, schema browsing, stored procedure calls, and transaction management. Supports multiple database connections with safety features like read-only mode and dangerous query detection.
Updated 6 months ago (2026-02-14 11:23 UTC)
16
MIT
safe-sql-mcp
Databases Developer Tools
ahmedabdirahman1-max
F
license
Not graded
quality
C
maintenance
Enables read-only SQL database access for AI assistants, allowing schema exploration and safe query execution without risk of data modification.
Updated 2 months ago (2026-06-14 18:23 UTC)
DB Insights MCP Server
Databases Developer Tools
six-eyes-dev
F
license
Not graded
quality
C
maintenance
Enables AI assistants to query SQL databases safely with read-only access, allowing schema discovery and SELECT queries while blocking writes and DDL operations.
Updated 2 months ago (2026-06-17 13:19 UTC)
oradb-explorer-mcp
Databases Search
arun-siv
F
license
Not graded
quality
B
maintenance
Enables read-only exploration of Oracle databases through natural language, providing schema inspection and safe bounded SQL query execution.
Updated 15 days ago (2026-08-08 18:39 UTC)

View all related MCP servers

Related MCP Connectors

BankBridge
Read-only bank access for your AI agent. Connects Claude, ChatGPT, Cursor, Gemini, Codex.
PlainQuery | MCP DB Agent
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
saferagenticai-mcp
Read-only tools over the Safer Agentic AI framework: 238 patterns + 14 heuristics.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sharat9703/oracle-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

oracle-mcp

目录

功能特性

环境要求

安装

配置

数据库（一个或多个）

共享设置

接入代理

架构

工具参考

安全考虑

示例

测试

故障排查

许可证

Maintenance

Resources

Looking for Admin?

Related MCP Servers

Oracle DB MCP Server

safe-sql-mcp

DB Insights MCP Server

oradb-explorer-mcp

Related MCP Connectors

Latest Blog Posts

MCP directory API