甲骨文MCP服务器

Name: 甲骨文MCP服务器
Author: smith-nathanh

作者：smith-nathanh2 星标更新：2025-08-28

安装使用来源：spider==github.com

项目介绍

Oracle MCP Server

Oracle Database MCP Server - 执行SQL查询、浏览模式并分析性能。

概述

此模型上下文协议（MCP）服务器为AI助手和开发环境提供了全面的Oracle数据库交互能力。通过任何兼容MCP的客户端安全地执行SQL查询、浏览数据库模式、分析查询性能、以多种格式导出数据，并获得智能数据库见解。

功能

安全查询执行 - 使用内置的安全控制执行SELECT查询
模式检查 - 浏览数据库表、视图、过程和函数
性能分析 - 获取执行计划和查询性能指标
数据导出 - 将查询结果导出为JSON和CSV格式
安全控制 - 表/列白名单和只读操作强制

查询执行功能

MCP服务器提供丰富的查询执行功能，并带有自动安全控制：

自动行限制：SELECT查询自动限制以防止资源耗尽（可通过QUERY_LIMIT_SIZE配置）
SQL注入防护：内置关键字过滤阻止危险操作（如DROP、DELETE、UPDATE等）
智能查询增强：没有明确ROWNUM/LIMIT子句的查询会自动分页
数据类型处理：自动转换Oracle特定类型（如LOB、DATE、NUMBER）到可序列化为JSON的格式
执行指标：每个查询返回执行时间和行数统计

示例查询响应：

{
  "columns": ["EMPLOYEE_ID", "FIRST_NAME", "LAST_NAME", "SALARY"],
  "rows": [[100, "Steven", "King", 24000], [101, "Neena", "Kochhar", 17000]],
  "row_count": 2,
  "execution_time_seconds": 0.045,
  "query": "SELECT employee_id, first_name, last_name, salary FROM employees WHERE ROWNUM <= 100"
}

模式检查功能

服务器提供全面的数据库元数据，帮助LLMs理解您的数据库结构：

表发现：列出所有可访问的表及其行数、最后分析日期和注释
列详情：提供数据类型、空值约束、默认值和列注释
关系洞察：视图及其底层表的关系
存储过程：可用的函数、过程和包及其状态

示例表元数据：

{
  "owner": "HR",
  "table_name": "EMPLOYEES",
  "columns": [
    {
      "column_name": "EMPLOYEE_ID",
      "data_type": "NUMBER",
      "nullable": "N",
      "column_comment": "员工表的主键"
    },
    {
      "column_name": "FIRST_NAME",
      "data_type": "VARCHAR2",
      "data_length": 20,
      "nullable": "Y",
      "column_comment": "员工的名字"
    }
  ],
  "table_comment": "包括工资和部门的员工信息"
}

性能分析特性

执行计划：生成并分析带有成本估算的查询执行计划
查询优化：识别表扫描、索引使用和性能瓶颈
资源估计：查询操作的成本、基数和字节估计

GitHub Copilot Agent交互

Oracle MCP Server在GitHub Copilot中的应用

示例展示了Oracle MCP Server如何通过GitHub Copilot的代理模型接口响应数据库查询

当GitHub Copilot与MCP服务器交互时，它接收结构化的数据，这使得复杂的数据库辅助成为可能，包括查询生成、模式理解和性能优化建议。

文档

📚 设置指南：

Docker示例设置 - 完整的Oracle数据库Docker示例，包含样本数据
完整的设置指南 - 任何Oracle数据库的逐步安装说明
快速参考 - 凭证、命令和故障排除

🐳 新接触Oracle？ 从Docker示例开始，在几分钟内运行起来！

快速设置

先决条件

Python 3.10+
UV包管理器
Oracle数据库访问权限
Oracle Instant Client（用于高级功能）

安装

克隆并设置项目：

git clone <repository-url>
cd oracle-mcp-server
./setup.sh

配置数据库连接：

cp .env.example .env
# 编辑.env文件，填写您的Oracle数据库详细信息

测试连接：
```
uv run oracle-mcp-server --debug
```
替代方案：使用启动脚本进行自动环境设置：
```
./start_mcp_server.sh --debug
```
设置VS Code集成： 请参阅下方的VS Code集成部分获取详细的设置说明。

聊天演示（mcp-chat）

🤖 想了解LLM如何逐步使用MCP工具吗？

mcp-chat演示展示了代理如何连接并查询您的Oracle数据库。该演示展示了LLM在使用MCP服务器回答数据库问题时遵循的原始工具使用模式。

特性

直接工具使用：实时观看LLM调用MCP工具
逐步进展：查看每次工具调用发生的情况
多模型支持：适用于任何OpenRouter兼容模型
可配置超时：控制复杂查询可以运行的时间

快速开始

# 1. 设置您的OpenRouter API密钥
export OPENROUTER_API_KEY="your-api-key-here"

# 2. 设置数据库连接（使用Docker示例或您自己的数据库）
export DB_CONNECTION_STRING="testuser/TestUser123!@localhost:1521/testdb"

# 3. 运行一个简单的查询
uv run mcp-chat "数据库中有哪些表？"

# 4. 使用特定模型运行更复杂的查询
uv run mcp-chat --model openai/gpt-4.1 "哪个部门的员工薪酬最高？"

示例：多轮次工具使用

这里展示了询问“哪个部门的员工薪酬最高？”时会发生什么——请注意，LLM会多次调用工具来收集信息，然后再给出答案：

$ uv run mcp-chat --model google/gemini-2.5-flash --timeout 120 "哪个部门的员工薪酬最高？"
使用模型：google/gemini-2.5-flash
╭────────────────────────────────── 欢迎 ───────────────────────────────────╮
│ Oracle数据库助手                                                    │
│ 我可以帮助您探索和查询您的Oracle数据库。                       │
│ 输入'exit'退出，'clear'重新开始。                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

您：哪个部门的员工薪酬最高？
正在处理您的请求...
分析（第1次迭代）...
使用工具：list_tables
执行list_tables...
   预览：{
  "tables": [
    {
      "owner": "TESTUSER",
      "table_name": "DEPARTMENTS",
      "num_rows": 3,
      "last_analyzed": "2025-07-14T22:00:12",
      "table_comment": null,
      "tablespace_na...
分析（第2次迭代）...
使用工具：describe_table
执行describe_table...
   预览：{
  "table_name": "EMPLOYEES",
  "owner": null,
  "columns": [
    {
      "column_name": "ID",
      "data_type": "NUMBER",
      "data_length": 22,
      "data_precision": 10,
      "data_scale": 0,...
分析（第3次迭代）...
使用工具：describe_table
执行describe_table...
   预览：{
  "table_name": "DEPARTMENTS",
  "owner": null,
  "columns": [
    {
      "column_name": "ID",
      "data_type": "NUMBER",
      "data_length": 22,
      "data_precision": 10,
      "data_scale": ...
分析（第4次迭代）...
使用工具：execute_query
执行execute_query...
   预览：{
  "columns": [
    "DEPARTMENT_NAME"
  ],
  "rows": [
    [
      "Engineering"
    ]
  ],
  "row_count": 1,
  "execution_time_seconds": 0.002093,
  "query": "SELECT * FROM (SELECT d.name AS departm...
分析（第5次迭代）...
准备回应
预览：薪酬最高的员工所在的部门是工程部。
处理完成

助手：
薪酬最高的员工所在的部门是工程部。

理解工具流程

在上述示例中，LLM遵循了逻辑步骤：

发现（list_tables）：首先探索有哪些表可用
模式理解（describe_table x2）：检查EMPLOYEES和DEPARTMENTS表的结构
查询执行（execute_query）：运行SQL查询
最终答案：根据查询数据提供具体结果

这展示了LLM如何将复杂的问题分解成离散的工具调用，逐步收集信息，然后综合得出最终答案。

命令选项

# 使用特定模型（默认：openai/gpt-4.1）
uv run mcp-chat --model openai/gpt-4.1 "您的问题"

# 为复杂查询设置自定义超时（默认：60秒）
uv run mcp-chat --timeout 120 "复杂分析问题"

# 启用调试日志
uv run mcp-chat --debug "您的问题"

# 交互模式（无初始问题）
uv run mcp-chat

# 获取帮助
uv run mcp-chat --help

支持的模型

聊天界面适用于任何OpenRouter兼容模型，但您可能希望使用擅长工具调用的模型，如openai/gpt-4.1。

最佳实践提示

具体提问：“按部门显示薪资”比“告诉我关于员工的信息”效果更好
观察进度：工具调用显示了LLM是如何思考的
调整超时：复杂的分析查询可能需要更多时间
尝试不同的模型：某些模型更适合多步指令

用于测试的Docker设置

🐳 新接触Oracle？ 在几分钟内运行一个完整的测试环境！

我们提供了一个现成的Docker设置，包含Oracle Database XE和样本数据。非常适合：

测试MCP服务器
学习Oracle数据库交互
开发和原型设计

快速开始

# 1. 启动带有样本数据的Oracle数据库
cd docker-example
docker-compose up -d

# 2. 配置MCP服务器
cp .env.docker ../.env

# 3. 测试设置
cd .. && uv run oracle-mcp-server --version

您将获得

运行在Docker中的Oracle Database XE 21c
样本数据库，包含员工和部门表
测试用户（testuser/TestUser123!），具有适当的权限
用于MCP服务器的现成连接字符串

📖 完整的Docker设置指南 →

Docker示例包括详细的说明、故障排除、样本查询和管理命令。

VS Code集成

先决条件

安装VS Code扩展：
- GitHub Copilot - MCP集成所需
- Python - 推荐用于开发

设置步骤

完成基本设置（参见上方的快速设置部分）
配置环境变量：
- 确保您的.env文件中正确设置了DB_CONNECTION_STRING
- VS Code将自动从.env文件加载环境变量

MCP配置： 项目包含预配置的.vscode/mcp.json文件：

{
  "servers": {
    "oracle-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "-m", "oracle_mcp_server.server"],
      "env": {
        "DB_CONNECTION_STRING": "${env:DB_CONNECTION_STRING}",
        "DEBUG": "${env:DEBUG}",
        "QUERY_LIMIT_SIZE": "${env:QUERY_LIMIT_SIZE}",
        "MAX_ROWS_EXPORT": "${env:MAX_ROWS_EXPORT}"
      }
    }
  }
}

激活MCP服务器：
- 在VS Code中打开该项目文件夹
- 重启VS Code以加载MCP配置
- 当GitHub Copilot需要时，Oracle MCP服务器将自动启动

使用MCP服务器

一旦配置好，您可以通过GitHub Copilot与您的Oracle数据库互动：

询问数据库问题：
- “显示数据库中的所有表”
- “描述EMPLOYEES表的结构”
- “最近的订单是什么？”
查询协助：
- “生成一个查询以查找来自加利福尼亚的所有客户”
- “解释这个查询的执行计划”
- “将结果导出为CSV”
模式探索：
- “有哪些视图可用？”
- “展示PRODUCTS表的样本数据”
- “列出所有存储过程”

故障排除VS Code集成

MCP服务器未启动：

检查VS Code的输出面板 → "GitHub Copilot Chat"中的错误消息
验证.env文件存在且有正确的DB_CONNECTION_STRING
确保uv已安装并在PATH中
完全重启VS Code

连接问题：

手动测试连接：uv run oracle-mcp-server --debug
检查Oracle数据库是否可访问
验证.env文件中的凭据

没有数据库响应：

确保GitHub Copilot扩展已激活
检查工作区中是否存在.vscode/mcp.json
验证环境变量是否加载（检查VS Code终端：echo $DB_CONNECTION_STRING）

替代方案：使用启动脚本

对于需要显式环境设置的MCP服务器，您可以使用包含的启动脚本：

# 使用启动脚本而不是直接执行Python
./start_mcp_server.sh --version

启动脚本自动：

激活Python虚拟环境
从.env文件加载环境变量
验证数据库连接字符串可用
使用正确的配置启动MCP服务器

要与VS Code MCP配置一起使用，请更新.vscode/mcp.json：

{
  "servers": {
    "oracle-mcp-server": {
      "command": "./start_mcp_server.sh",
      "args": [],
      "cwd": "${workspaceFolder}"
    }
  }
}

这在以下情况下特别有用：

环境变量无法自动加载
虚拟环境未被检测到
您需要在不同环境中保持一致的启动行为

使用VS Code开发

项目包含VS Code特定的配置：

Python解释器：自动使用UV虚拟环境
文件关联：SQL文件被正确识别
GitHub Copilot：启用Python和SQL文件
调试：使用F5直接调试MCP服务器

配置

环境变量

变量	描述	默认值	示例
`DB_CONNECTION_STRING`	Oracle连接字符串	必需	`oracle+oracledb://hr:password@localhost:1521/?service_name=XEPDB1`
`TABLE_WHITE_LIST`	允许的表的逗号分隔列表	所有表	`EMPLOYEES,DEPARTMENTS`
`COLUMN_WHITE_LIST`	允许的列的逗号分隔列表	所有列	`EMPLOYEES.ID,EMPLOYEES.NAME`
`QUERY_LIMIT_SIZE`	每个查询返回的最大行数	`100`	`500`
`MAX_ROWS_EXPORT`	导出操作的最大行数	`10000`	`50000`
`DEBUG`	启用调试日志	`False`	`True`

连接字符串示例

# Docker测试数据库（来自本项目的设置）
DB_CONNECTION_STRING="testuser/TestUser123!@localhost:1521/testdb"

# 本地Oracle XE（传统格式）
DB_CONNECTION_STRING="oracle+oracledb://system:password@localhost:1521/?service_name=XE"

# Oracle云自治数据库
DB_CONNECTION_STRING="oracle+oracledb://admin:password@hostname:1522/?service_name=your_service_tls&ssl_context=true"

# 生产环境带连接池
DB_CONNECTION_STRING="oracle+oracledb://app_user:password@db.company.com:1521/?service_name=PROD&pool_size=10"

注意：MCP服务器支持两种连接字符串格式：

简单格式：username/password@host:port/service_name（推荐用于Docker设置）
URL格式：oracle+oracledb://username:password@host:port/?service_name=service_name（为了兼容性）

可用工具

当与GitHub Copilot集成时，以下工具可用：

execute_query - 执行SELECT、DESCR

甲骨文MCP服务器

项目介绍

Oracle MCP Server

目录

概述

功能

查询执行功能

模式检查功能

性能分析特性

GitHub Copilot Agent交互

文档

快速设置

先决条件

安装

聊天演示（mcp-chat）

特性

快速开始

示例：多轮次工具使用

理解工具流程

命令选项

支持的模型

最佳实践提示

用于测试的Docker设置

快速开始

您将获得

VS Code集成

先决条件

设置步骤

使用MCP服务器

故障排除VS Code集成

替代方案：使用启动脚本

使用VS Code开发

配置

环境变量

连接字符串示例

可用工具