一个模型上下文协议 (MCP) 服务器，使 GitHub Copilot 和其他 LLM 能够对 Oracle 数据库执行只读 SQL 查询。
Related MCP server: MCP Server for Oracle Database
这是 Mac 用户的推荐路径。我们使用 Colima 作为 Docker 运行时（比 Docker Desktop 更轻量，且在 Apple Silicon 上原生运行），并从源代码构建 MCP 服务器。
Homebrew（如果已安装则跳过）：
/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 CLI：
brew install colima dockerColima 是 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然后使用上述标志重启。
Oracle 的容器注册表要求在拉取镜像前拥有一个免费账户。
在 https://container-registry.oracle.com 创建一个免费账户
登录，导航至 Database → express，然后点击 Accept License Agreement
从终端登录：
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
SYSTEM 密码： OraclePwd123
Web UI (EM Express)： http://localhost:5500/em
服务名称说明： Oracle XE 21c 有两个服务名称：
XE— 容器数据库 (CDB)，用于 SYSTEM 用户
XEPDB1— 可插拔数据库 (PDB)，用于常规应用程序用户
稍后启动和停止数据库：
docker start oracle-xe
docker stop oracle-xegit clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run buildcp .env.example .env编辑 .env 以使用本地 Oracle XE（适合试用）：
ORACLE_CONNECTION_STRING=localhost:1521/XE
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123对于生产环境，请先创建一个专用的只读用户 — 参见 创建只读用户。
# 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: ✅参见下方的 配置 VS Code。
为你提供最新代码，并允许你在连接到 Copilot 之前运行测试套件以验证一切正常。
git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build如果你只想获取服务器二进制文件而无需克隆源代码：
npm install -g mcp-oracle-database在你的 VS Code 工作区中创建 .vscode/mcp.json（或添加到你的全局 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）。
{
"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 并在 Agent 模式下打开 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 Thin 模式（纯 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" }用于全面模式自省的五种专用工具：
工具 | 用途 | 缓存 |
| 所有可访问的表，包含元数据和可选的行数 | ✅ |
| 列类型、约束、主键/外键 | ✅ |
| JSON 格式的外键关系 | ✅ |
| 用于理解数据格式的样本值 | ❌ |
| 通过外键、命名、共享列查找相关表 | ❌ |
📖 参见 模式发现文档 获取完整详细信息和示例。
"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 或作为 VS Code MCP 配置中的 env 键。
# 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 testsmcp-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 status
colima start --cpu 2 --memory 4 # Oracle needs at least 2GB RAM
docker ps # verify Docker is available# 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: healthyError: ORA-12545: Connect failed because target host or object does not existOracle 是否在运行？ docker ps | grep oracle-xe
检查端口是否已映射：docker ps 应显示 0.0.0.0:1521->1521/tcp
SYSTEM 用户尝试 localhost:1521/XE，其他用户尝试 localhost:1521/XEPDB1
服务 | 用途 |
| SYSTEM 用户，DBA 操作 |
| 常规应用程序用户 |
Error: ORA-00942: table or view does not exist授予用户 SELECT 权限：
GRANT SELECT ANY TABLE TO your_user;Error: unauthorized: authentication required在 https://container-registry.oracle.com 创建一个免费账户
接受 Database → express 的许可协议
运行 docker login container-registry.oracle.com
Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS在 .env 或你的 VS Code MCP 配置中提高限制：
MCP_MAX_RESPONSE_CHARS=100000本项目使用 node-oracledb Thin 模式 — 一种纯 JavaScript 驱动程序，无需 Oracle Instant Client。它适用于包括 Apple Silicon Mac 在内的所有平台。
📚 集成指南：
模式发现指南 — 高级模式自省工具
模式发现快速参考 — 所有发现工具的速查表
模式发现示例 — MCP 消息示例
VS Code 集成指南 — 与 GitHub Copilot 设置
Claude Desktop 集成指南 — 与 Claude Desktop 设置
MCP 集成指南 — MCP 协议深度解析
架构概览 — 系统架构图
日志配置 — 日志设置与配置
📝 自定义指令：
.github/copilot-instructions.md — 项目范围的 Copilot 指令
.github/instructions/ — 特定语言的编码准则
Oracle 是 Oracle Corporation 的注册商标。 本项目不隶属于 Oracle Corporation，也不受其认可或赞助。
本项目基于 GNU 通用公共许可证 v3.0 (GPLv3) 发布。
如果你选择 GPLv3，你将获得书面形式的 GPLv3 权利，且没有额外的用途限制。参见 LICENSE 获取完整许可文本，参见 LICENSE.md 获取简短许可概述。
对于希望获得替代条款（如协商的商业条款、保修承诺或专有分发权）的各方，作者可提供单独的商业许可。
📄 参见 LICENSE.md 获取许可概述。
📄 参见 COMMERCIAL_LICENSE.md 获取单独的商业/政府许可条款。
欢迎贡献！请提交 issue 或 pull request。
Get database schema information. If tableName is provided, returns column details for that table. Otherwise, returns a list of all accessible tables.
| Name | Required | Description | Default |
|---|---|---|---|
| tableName | No | Optional table name to get column information for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the tool's conditional behavior based on the tableName parameter, which is useful context. However, it doesn't disclose important behavioral traits like whether this requires specific permissions, what 'accessible tables' means in terms of access control, error handling for invalid table names, or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that efficiently convey all necessary information. The first sentence states the core purpose, and the second explains the conditional behavior. Every word earns its place with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only schema inspection tool with no annotations and no output schema, the description provides adequate basic information about what the tool does and how parameters affect behavior. However, it lacks details about return format, error conditions, access restrictions, or what 'accessible tables' encompasses, which would be helpful given the absence of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the tableName parameter clearly documented as optional. The description adds value by explaining the semantic impact of providing vs. not providing this parameter: it changes the return type from column details to a table list. However, it doesn't add syntax or format details beyond what the schema provides, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'database schema information', with specific conditional behavior: returns column details for a specific table if tableName is provided, otherwise returns a list of all accessible tables. This distinguishes it from the sibling tool 'query_database', which presumably executes queries rather than retrieving schema metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: use with tableName parameter to get column details for that table, or without parameter to get a list of all tables. However, it doesn't explicitly state when NOT to use it or mention alternatives like the sibling 'query_database' tool, which could be relevant for schema exploration vs. data querying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only SQL SELECT query against the Oracle database. Returns rows, column names, and execution metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SQL query to execute (SELECT statements only) | |
| maxRows | No | Maximum number of rows to return (optional) | |
| timeout | No | Query timeout in milliseconds (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively states the tool is 'read-only', which implies safety from mutations, and mentions return types and execution metrics, adding useful context. However, it lacks details on permissions, rate limits, error handling, or database-specific constraints, which are important for a database query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and concise, consisting of two sentences that efficiently convey the tool's purpose, constraints, and outputs without any wasted words. Every sentence earns its place by providing essential information, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (database querying with multiple parameters) and the absence of annotations and output schema, the description does a good job by specifying the query type, database, and return data. However, it could be more complete by including details on output format, error responses, or connection requirements, which would help an agent use it more effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as query syntax examples or default values for optional parameters. This meets the baseline score of 3, as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Execute a read-only SQL SELECT query') and resources ('against the Oracle database'), and distinguishes it from potential siblings by specifying it's for SELECT queries only. It explicitly mentions what it returns ('rows, column names, and execution metrics'), making the purpose unambiguous and comprehensive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool by specifying 'read-only SQL SELECT query' and 'SELECT statements only', which implicitly guides usage for data retrieval rather than modifications. However, it does not explicitly mention when not to use it or name alternatives like 'get_database_schema' for schema queries, leaving some room for improvement in sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_database_schemaquery_databaseScored across 2 tools
The two tools have clearly distinct purposes: get_database_schema retrieves metadata about the database structure, while query_database executes SQL queries for data retrieval. There is no overlap or ambiguity between them.
Both tools follow a consistent verb_noun naming pattern (get_database_schema, query_database) with clear, descriptive names that align with their functions. The naming is uniform and predictable.
With only 2 tools, the server feels under-scoped for an Oracle Database MCP Server, as it lacks essential operations like data manipulation (INSERT, UPDATE, DELETE), transaction management, or administrative tasks, making it incomplete for typical database workflows.
The tool surface is severely incomplete for a database server, covering only schema inspection and read-only queries. Missing are critical operations such as data modification, stored procedure execution, user management, and other core database functionalities, leading to significant gaps.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
