# oracle-mcp

**Repository Path**: chusj/oracle-mcp

## Basic Information

- **Project Name**: oracle-mcp
- **Description**: 让AI IDE方便操作oracle数据库的mcp
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-09
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Oracle Database MCP Server

这是一个基于 Python 实现的 Model Context Protocol (MCP) 服务器，旨在让大语言模型（LLM）能够安全、便捷地访问和操作 Oracle 数据库。

通过此 MCP 服务器，您的 AI 助手可以执行 SQL 查询、分析表结构以及获取数据库中的数据，从而辅助进行数据分析、报表生成或系统调试。

## ✨ 功能特性

*   **执行 SQL 查询**: 支持执行 `SELECT` 查询语句以获取数据。
*   **浏览数据库架构**:
    *   列出当前用户下的所有表。
    *   查看指定表的详细结构（列名、数据类型等）。
*   **基于 Python**: 使用 `python-oracledb` 驱动，支持 Thin 模式（无需安装 Oracle Client）和 Thick 模式。
*   **安全可控**: 建议配置只读权限的数据库账号以确保安全。

## 🛠️ 前置要求

*   Python 3.10 或更高版本
*   访问 Oracle 数据库的权限（主机名、端口、服务名/SID、用户名、密码）
*   `uv` (推荐) 或 `pip` 用于包管理

## 🚀 安装与配置

### 1. 克隆项目

```bash
git clone <repository-url>
cd oracle-mcp
```

### 2. 安装依赖

建议使用虚拟环境管理依赖。

```bash
# 创建并激活虚拟环境 (Windows)
python -m venv .venv
.venv\Scripts\activate

# 安装依赖
pip install mcp python-oracledb
```

### 3. 环境变量配置

为了连接到 Oracle 数据库，您需要提供连接信息。可以通过环境变量或直接在 MCP 客户端配置中传递参数。

主要需要的参数：
*   `ORACLE_USER`: 数据库用户名
*   `ORACLE_PASSWORD`: 数据库密码
*   `ORACLE_DSN`: 数据源名称 (例如 `localhost:1521/orclpdb1`)

## 📖 使用指南

### 在 Claude Desktop 中使用

编辑您的 Claude Desktop 配置文件（通常位于 `%APPDATA%\Claude\claude_desktop_config.json`），添加以下配置：

```json
{
  "mcpServers": {
    "oracle-mcp": {
      "command": "F:/trae-proj/oracle-mcp/.venv/Scripts/python.exe",
      "args": [
        "F:/trae-proj/oracle-mcp/code/server.py"
      ],
      "env": {
        "ORACLE_USER": "your_username",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_DSN": "localhost:1521/orclpdb1"
      }
    }
  }
}
```

> 注意：
> 1. 请将 `F:/trae-proj/oracle-mcp/code/server.py` 替换为您实际的入口文件路径；
> 2. 将 `command` 指向项目本地虚拟环境的 Python 可执行文件（例如 `.venv/Scripts/python.exe`），以确保依赖（mcp、python-oracledb）在同一解释器下可用。
> 3. windows环境将单斜杠替换为`\\`，举例：`"F:\\trae-proj\\oracle-mcp\\code\\server.py"`

### 调试运行

您可以直接在终端运行服务器进行测试（通常通过 MCP 检查器或 stdio 交互）：

```bash
python code/server.py
```

## 🧰 可用工具 (Tools)

此 MCP Server 默认提供以下工具供 LLM 调用：

1.  **`list_tables`**
    *   描述: 列出当前数据库用户可访问的所有表名。
    *   参数: 无

2.  **`describe_table`**
    *   描述: 获取指定表的结构信息（列名、类型、是否为空等）。
    *   参数:
        *   `table_name` (string): 表名。

3.  **`execute_sql`**
    *   描述: 执行 SQL SELECT 查询语句。
    *   参数:
        *   `sql` (string): 要执行的 SQL 语句。
    *   *安全提示*: 建议仅允许 SELECT 语句，防止数据被修改。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进此项目！

## 📄 许可证

MIT License