Oracle数据库MCP服务器
一个模型上下文协议（MCP）服务器，使GitHub Copilot和其他LLM能够对Oracle数据库执行只读SQL查询。
](https://www.npmjs.com/package/mcp-oracle-database) 
______________________________________________________________________
目录
______________________________________________________________________
🍎 macOS设置（苹果硅-M1/M2/M3/M4）
这是Mac用户的推荐路径。我们使用 大肠杆菌 作为Docker运行时（比Docker Desktop轻，在Apple Silicon上原生工作），并从源代码构建MCP服务器。
步骤1--安装先决条件
家酿 （如果已安装，请跳过）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Node.js v18+ 通过nvm（推荐）：
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reload your shell config, then install Node
source ~/.zshrc
nvm install 20
nvm use 20
node --version # should print v20.x.x或者通过Homebrew：
brew install node
node --versionColima+Docker命令行界面:
brew install colima docker第二步——开始绞痛
Colima是macOS的轻量级容器运行时，不需要Docker Desktop。
# Start with enough resources for Oracle XE (needs at least 2GB RAM)
colima start --cpu 2 --memory 4 --disk 30
# Verify Docker is working
docker ps如果您已经有Colima在内存较少的情况下运行，请运行 colima stop 然后用上面的标志重新开始。步骤3--拉取并启动Oracle XE
Oracle的容器注册表需要 免费账户 在您可以提取图像之前。
- 在以下网址创建免费帐户https://container-registry.oracle.com
- 登录，导航到 数据库→ 表达，然后单击 接受许可协议
- 从您的终端登录：
docker login container-registry.oracle.com
# Enter your Oracle account email and password when prompted- 拉取并运行Oracle XE 21c：
docker run -d \
--name oracle-xe \
-p 1521:1521 \
-p 5500:5500 \
-e ORACLE_PWD=OraclePwd123 \
container-registry.oracle.com/database/express:latest- 等待它准备就绪（首次启动需要60-90秒）：
# Poll health status — wait for "healthy"
watch -n 5 'docker inspect --format="{{.State.Health.Status}}" oracle-xe'
# Or tail the logs directly
docker logs -f oracle-xe
# Look for: DATABASE IS READY TO USE!您的数据库现在位于：
- 连接字符串：
localhost:1521/XE - 系统密码：
OraclePwd123 - Web UI（EM Express）： http://localhost:5500/em
服务名称注释： Oracle XE 21c有两个服务名称： -XE--与SYSTEM用户一起使用的容器数据库（CDB） -XEPDB1--可插拔数据库（PDB），用于常规应用程序用户
要稍后启动和停止数据库，请执行以下操作：
docker start oracle-xe
docker stop oracle-xe步骤4——克隆并构建MCP服务器
git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build步骤5——配置环境
cp .env.example .env编辑 .env 对于本地Oracle XE（适合试用）：
ORACLE_CONNECTION_STRING=localhost:1521/XE
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123对于生产使用，请先创建一个专用的只读用户——请参阅 创建只读用户.
步骤6——测试服务器
# Core tests: connects to Oracle, queries schema and version
npm run test-client
# Schema discovery tool tests
npm run test-discovery预期产量：
✅ All tests completed successfully!
📊 Test Summary:
1. List Tools: ✅
2. List Tables (fast): ✅
3. List Tables (with counts): ✅
4. Describe Table: ✅
5. Get Table Relations: ✅
6. Get Sample Values: ✅
7. Suggest Related Tables: ✅
8. Cache Test: ✅步骤7——连接VS代码
看 配置VS代码 在......下面
______________________________________________________________________
📦 安装
从源代码构建（推荐）
为您提供最新代码，并允许您在连接到Copilot之前运行测试套件以验证一切正常。
git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build从npm安装
如果你只想要服务器二进制文件而不克隆源代码：
npm install -g mcp-oracle-database______________________________________________________________________
🔌 配置VS代码
选项A——来源（推荐）
创建 .vscode/mcp.json 在VS Code工作区中（或添加到全局MCP配置中）：
{
"servers": {
"oracleDatabase": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp-oracle-database/dist/server.js"],
"env": {
"ORACLE_CONNECTION_STRING": "localhost:1521/XE",
"ORACLE_USER": "system",
"ORACLE_PASSWORD": "OraclePwd123",
"ORACLE_POOL_MIN": "2",
"ORACLE_POOL_MAX": "10",
"QUERY_TIMEOUT_MS": "30000",
"MAX_ROWS_PER_QUERY": "1000",
"ENFORCE_READ_ONLY_QUERIES": "true",
"MCP_MAX_RESPONSE_CHARS": "50000",
"MCP_MAX_ROWS_IN_RESPONSE": "200",
"MCP_MAX_STRING_LENGTH": "500"
}
}
}
}替换 /absolute/path/to/mcp-oracle-database 使用机器上的真实路径（例如。 /Users/yourname/GITHUB/mcp-oracle-database).
选项B——从npm全局安装
{
"servers": {
"oracleDatabase": {
"type": "stdio",
"command": "mcp-database-server",
"env": {
"ORACLE_CONNECTION_STRING": "localhost:1521/XE",
"ORACLE_USER": "your_user",
"ORACLE_PASSWORD": "your_password",
"ORACLE_POOL_MIN": "2",
"ORACLE_POOL_MAX": "10",
"QUERY_TIMEOUT_MS": "30000",
"MAX_ROWS_PER_QUERY": "1000",
"ENFORCE_READ_ONLY_QUERIES": "true",
"MCP_MAX_RESPONSE_CHARS": "50000",
"MCP_MAX_ROWS_IN_RESPONSE": "200",
"MCP_MAX_STRING_LENGTH": "500"
}
}
}
}保存配置后，重新加载VS Code并在中打开Copilot聊天 代理模式。尝试：
"What tables are in the database?"
"Describe the HELP table"
"Show me 5 rows from the HELP table"______________________________________________________________________
可选：创建只读用户
使用 SYSTEM 对于本地测试来说很好，但对于任何真实的数据库，创建一个专用的只读用户。
连接到Oracle（例如通过 sqlplus 或类似DBeaver的GUI）：
-- For Oracle XE local Docker, connect with:
-- sqlplus system/OraclePwd123@localhost:1521/XEPDB1
CREATE USER readonly_user IDENTIFIED BY secure_password;
GRANT CREATE SESSION TO readonly_user;
GRANT SELECT ANY TABLE TO readonly_user;
-- Or restrict to specific tables:
-- GRANT SELECT ON myschema.orders TO readonly_user;
-- GRANT SELECT ON myschema.customers TO readonly_user;然后更新您的 .env 或MCP配置：
ORACLE_CONNECTION_STRING=localhost:1521/XEPDB1
ORACLE_USER=readonly_user
ORACLE_PASSWORD=secure_password______________________________________________________________________
特性
- 🔒 只读访问 --使用专用只读数据库用户进行安全保护
- 📡 stdio传输 --通过标准输入/输出进行通信（不需要HTTP服务器）
- ⚡ 连接池 --高效的Oracle连接管理
- 📊 模式自省 --查询表和列信息
- 🔍 高级架构发现 --5个用于发现表、关系和数据模式的专用工具
- 💾 内存缓存 --使用LRU缓存快速重复访问（5分钟TTL）
- 📝 审计日志 --所有记录了执行指标的查询
- ⏱️ 超时保护 --防止长时间运行的查询
- 🛡️ 结果限制 --可配置的行限制，以防止内存问题
- 🍎 无需Oracle客户端 --使用node oracledb瘦模式（纯JS，适用于Apple Silicon）
建筑
GitHub Copilot / LLM
↓ (MCP Protocol)
MCP Client (spawns process)
↓ (JSON-RPC over stdio)
MCP Server (Node.js)
↓ (node-oracledb Thin Mode)
Oracle Database (read-only user)______________________________________________________________________
可用工具
核心工具
query_database
执行只读SQL SELECT查询。
{
"query": "SELECT table_name FROM user_tables FETCH FIRST 10 ROWS ONLY",
"maxRows": 10
}get_database_schema
获取特定表的表列表或列详细信息。
{ "tableName": "ORDERS" }架构发现工具
五种用于全面模式内省的专用工具：
| 工具 | 目的 | 缓存 |
|---|---|---|
listTables | 所有具有元数据和可选行数的可访问表 | ✅ |
describeTable | 列类型、约束、主键/外键 | ✅ |
getTableRelations | JSON中的外键关系 | ✅ |
getSampleValues | 用于理解数据格式的示例值 | ❌ |
suggestRelatedTables | 按FK、命名、共享列查找相关表 | ❌ |
📖 看 架构发现文档 查看完整的细节和示例。
副驾驶提示示例
"List all tables in the database"
"Describe the ORDERS table and its relationships"
"How many active users are there?"
"What are the top 5 products by sales this month?"
"Show me recent transactions for customer ID 12345"______________________________________________________________________
配置参考
所有设置都可以进入 .env 或作为 env 在VS Code MCP配置中键入。
# Oracle Database Connection
ORACLE_CONNECTION_STRING=localhost:1521/XE # host:port/service
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123
# Connection Pool
ORACLE_POOL_MIN=2
ORACLE_POOL_MAX=10
# Query Safety
QUERY_TIMEOUT_MS=30000 # max query time in ms
MAX_ROWS_PER_QUERY=1000 # max rows Oracle will fetch
MAX_QUERY_LENGTH=50000 # max SQL length in chars
ENFORCE_READ_ONLY_QUERIES=true # reject non-SELECT statements
# MCP Response Limits
MCP_MAX_RESPONSE_CHARS=50000 # hard cap on total response size
MCP_MAX_ROWS_IN_RESPONSE=200 # max rows per tool call response
MCP_MAX_STRING_LENGTH=500 # max chars per string field
# Logging
LOG_LEVEL=info
ENABLE_AUDIT_LOGGING=true
ENABLE_FILE_LOGGING=true
LOG_DIR=./logs
NODE_ENV=development大型架构： 如果你的数据库有500多个表，提高MCP_MAX_RESPONSE_CHARS到100000.
______________________________________________________________________
发展
脚本
npm run build # Compile TypeScript → dist/
npm run dev # Watch mode compilation
npm run clean # Remove dist/
npm run typecheck # Type-check without compiling
npm start # Start MCP server (requires build first)
npm run test-client # Core tool tests against live Oracle DB
npm run test-discovery # Schema discovery tool tests项目结构
mcp-oracle-database/
├── src/
│ ├── server.ts # MCP server entry point
│ ├── client.ts # Core test client
│ ├── test-discovery.ts # Discovery tools test client
│ ├── config.ts # Zod-validated configuration
│ ├── database/
│ │ ├── oracleConnection.ts # Connection pool manager
│ │ ├── queryExecutor.ts # Query execution + safety checks
│ │ └── types.ts
│ ├── tools/
│ │ ├── queryDatabase.ts # query_database tool
│ │ ├── getSchema.ts # get_database_schema tool
│ │ └── discovery/ # 5 schema discovery tools + cache
│ └── utils/
│ ├── logger.ts # Lightweight file + console logger
│ └── responseFormatter.ts # MCP response size management
├── dist/ # Compiled output (git-ignored)
├── .env # Your credentials (git-ignored)
├── .env.example # Template
└── package.json______________________________________________________________________
安全注意事项
- 只读用户 --数据库用户在生产环境中应仅具有SELECT权限
- 无注射保护 --服务器信任LLM生成有效的SQL；只读用户是安全网
- 查询限制 --行数和超时限制可防止资源耗尽
- 审计日志 --所有查询都记录了时间戳以供查看
- 本地使用 --此服务器旨在直接在您的计算机上运行；它可以在本地运行，但仍然可以访问远程数据库。
______________________________________________________________________
故障排除
Colima未运行（macOS）
colima status
colima start --cpu 2 --memory 4 # Oracle needs at least 2GB RAM
docker ps # verify Docker is availableOracle容器问题
# Check if container exists
docker ps -a | grep oracle-xe
# View startup logs
docker logs oracle-xe
# Already exists but stopped — just start it
docker start oracle-xe
# Check health status
docker inspect --format='{{.State.Health.Status}}' oracle-xe
# Wait for: healthy连接失败
Error: ORA-12545: Connect failed because target host or object does not exist- Oracle正在运行吗？
docker ps | grep oracle-xe - 检查端口是否已映射：
docker ps应显示0.0.0.0:1521->1521/tcp - 尝试
localhost:1521/XE对于SYSTEM用户，localhost:1521/XEPDB1对于其他用户
服务名称错误
| 服务 | 用于 |
|---|---|
localhost:1521/XE | 系统用户、DBA操作 |
localhost:1521/XEPDB1 | 常规应用程序用户 |
权限不足
Error: ORA-00942: table or view does not exist向您的用户授予SELECT：
GRANT SELECT ANY TABLE TO your_user;需要Oracle容器注册表登录
Error: unauthorized: authentication required- 在以下网址创建免费帐户https://container-registry.oracle.com
- 接受许可证 数据库→ 表达
- 跑
docker login container-registry.oracle.com
响应太大
Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS提高限额 .env 或您的VS代码MCP配置：
MCP_MAX_RESPONSE_CHARS=100000薄型模式注释
此项目使用节点oracledb 薄型模式 --一个不需要Oracle即时客户端的纯JavaScript驱动程序。它适用于所有平台，包括苹果Silicon Mac。
______________________________________________________________________
文档
📚 集成指南：
- 架构发现指南 --高级模式自检工具
- 架构发现快速参考 --所有发现工具的备忘单
- 架构发现示例 --MCP消息示例
- VS代码集成指南 --使用GitHub Copilot进行设置
- Claude桌面集成指南 --使用Claude Desktop进行设置
- MCP集成指南 --MCP协议详解
- 架构概述 --系统架构图
- 日志配置 --日志设置和配置
📝 自定义说明：
- --项目范围内的副驾驶说明
- --特定语言编码指南
______________________________________________________________________
Oracle是Oracle公司的注册商标。 本项目不隶属于Oracle公司，也不由Oracle公司认可或赞助。
______________________________________________________________________