Skip to content
Back to search

oracle-mcp-server

MCP Server for working with large Oracle databases

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/danielmeppiel--oracle-mcp-server/badge.svg)](/listings/danielmeppiel--oracle-mcp-server)

HTML

<a href="/listings/danielmeppiel--oracle-mcp-server"><img src="/api/listings/danielmeppiel--oracle-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

This option requires installing and setting up the project locally:

1. **Prerequisites** - Python 3.12 or higher - Oracle database access - Oracle instant client (required for the `oracledb` Python package)

2. **Install UV** ```bash # Install uv using curl (macOS/Linux) curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using PowerShell (Windows) irm https://astral.sh/uv/install.ps1 | iex ``` Make sure to restart your terminal after installing uv.

3. **Project Setup** ```bash # Clone repository git clone https://github.com/yourusername/oracle-mcp-server.git cd oracle-mcp-server

# Create and activate virtual environment uv venv

# Activate (On Unix/macOS) source .venv/bin/activate

# Activate (On Windows) .venv\Scripts\activate

# Install dependencies uv pip install -e . ```

4. **Configure VSCode Settings** ```json "mcp": { "inputs": [ { "id": "db-password", "type": "promptString", "description": "Oracle DB Password", "password": true, } ], "servers": { "oracle": { "command": "/path/to/your/.local/bin/uv", "args": [ "--directory", "/path/to/your/oracle-mcp-server", "run", "main.py" ], "env": { "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>", "TARGET_SCHEMA":"", "CACHE_DIR":".cache", "THICK_MODE":"", // Optional: set to "1" to enable thick mode "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and if you want to set a non-default directory for client libraries "READ_ONLY_MODE":"1" // Optional: set to "0" to allow write operations (default: "1" for read-only) } } } } ``` - Replace the paths with your actual uv binary path and oracle-mcp-server directory path

For both options: - Replace the `ORACLE_CONNECTION_STRING` with your actual database connection string - The `TARGET_SCHEMA` is optional, it will default to the user's schema - The `CACHE_DIR` is optional, defaulting to `.cache` within the MCP server root folder - The `READ_ONLY_MODE` defaults to "1" (read-only) for security. Set to "0" only when write operations are needed

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 401 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Server - Oracle DB Context
  2. [English](README.md) | [中文](README-zh.md)
  3. A powerful Model Context Protocol (MCP) server that provides contextual database schema information for large Oracle databases, enabling AI assistants to understand and work with databases containing thousands of tables.
  4. ## Table of Contents
  5. - [Overview](#overview)
  6. - [Features](#features)
  7. - [Usage](#usage)
  8. - [Integration with GitHub Copilot in VSCode Insiders](#integration-with-github-copilot-in-vscode-insiders)
  9. - [Option 1: Using Docker (Recommended)](#option-1-using-docker-recommended)
  10. - [Option 2: Using UV (Local Installation)](#option-2-using-uv-local-installation)
  11. - [Starting the Server locally](#starting-the-server-locally)
  12. - [Available Tools](#available-tools)
  13. - [Architecture](#architecture)
  14. - [Connection Modes](#connection-modes)
  15. - [Thin Mode (Default)](#thin-mode-default)
  16. - [Thick Mode](#thick-mode)
  17. - [System Requirements](#system-requirements)
  18. - [Performance Considerations](#performance-considerations)
  19. - [Contributing](#contributing)
  20. - [License](#license)
  21. - [Support](#support)
  22. ## Overview
  23. The MCP Oracle DB Context server solves a critical challenge when working with very large Oracle databases: how to provide AI models with accurate, relevant database schema information without overwhelming them with tens of thousands of tables and relationships.
  24. By intelligently caching and serving database schema information, this server allows AI assistants to:
  25. - Look up specific table schemas on demand
  26. - Search for tables that match specific patterns
  27. - Understand table relationships and foreign keys
  28. - Get database vendor information
  29. ## Features
  30. - **Smart Schema Caching**: Builds and maintains a local cache of your database schema to minimize database queries
  31. - **Targeted Schema Lookup**: Retrieve schema for specific tables without loading the entire database structure
  32. - **Table Search**: Find tables by name pattern matching
  33. - **Relationship Mapping**: Understand foreign key relationships between tables
  34. - **Oracle Database Support**: Built specifically for Oracle databases
  35. - **MCP Integration**: Works seamlessly with GitHub Copilot in VSCode, Claude, ChatGPT, and other AI assistants that support MCP
  36. - **Read-Only Mode**: Default security mode that prevents write operations while allowing full read access
  37. ## Usage
  38. ### Integration with GitHub Copilot in VSCode Insiders
  39. To use this MCP server with GitHub Copilot in VSCode Insiders, follow these steps:
  40. 1. **Install VSCode Insiders**
  41. - Download and install the latest version of [VSCode Insiders](https://code.visualstudio.com/insiders/)
  42. 2. **Install GitHub Copilot Extension**
  43. - Open VSCode Insiders
  44. - Go to the Extensions marketplace
  45. - Search for and install "GitHub Copilot"
  46. 3. **Configure MCP Server**
  47. - **Recommended: [Using Docker](#option-1-using-docker-recommended)**
  48. - Alternative: [Using UV](#option-2-using-uv-local-installation)
  49. 4. **Enable Agent Mode**
  50. - Open Copilot chat in VSCode Insiders
  51. - Click on "Copilot Edits"
  52. - Choose "Agent mode"
  53. - Click the refresh button in the chat input to load the available tools
  54. After completing these steps, you'll have access to all database context tools through GitHub Copilot's chat interface.
  55. #### Option 1: Using Docker (Recommended)
  56. In VSCode Insiders, go to your user or workspace `settings.json` file and add the following:
  57. ```json
  58. "mcp": {
  59. "inputs": [
  60. {
  61. "id": "db-password",
  62. "type": "promptString",
  63. "description": "Oracle DB Password",
  64. "password": true,
  65. }
  66. ],
  67. "servers": {
  68. "oracle": {
  69. "command": "docker",
  70. "args": [
  71. "run",
  72. "-i",
  73. "--rm",
  74. "-e",
  75. "ORACLE_CONNECTION_STRING",
  76. "-e",
  77. "TARGET_SCHEMA",
  78. "-e",
  79. "CACHE_DIR",
  80. "-e",
  81. "THICK_MODE",
  82. "dmeppiel/oracle-mcp-server"
  83. ],
  84. "env": {
  85. "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
  86. "TARGET_SCHEMA":"",
  87. "CACHE_DIR":".cache",
  88. "THICK_MODE":"", // Optional: set to "1" to enable thick mode
  89. "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and you want to set a non-default directory for client libraries
  90. "READ_ONLY_MODE":"1" // Optional: set to "0" to allow write operations (default: "1" for read-only)
  91. }
  92. }
  93. }
  94. }
  95. ```
  96. When using Docker (recommended approach):
  97. - All dependencies are included in the container
  98. - Set `THICK_MODE=1` in the environment variables to enable thick mode if needed
  99. - If you use `THICK_MODE`, you can optionally set the path where Oracle Client libraries are installed with `ORACLE_CLIENT_LIB_DIR` if it differs from the default location.
  100. #### Option 2: Using UV (Local Installation)
  101. This option requires installing and setting up the project locally:
  102. 1. **Prerequisites**
  103. - Python 3.12 or higher
  104. - Oracle database access
  105. - Oracle instant client (required for the `oracledb` Python package)
  106. 2. **Install UV**
  107. ```bash
  108. # Install uv using curl (macOS/Linux)
  109. curl -LsSf https://astral.sh/uv/install.sh | sh
  110. # Or using PowerShell (Windows)
  111. irm https://astral.sh/uv/install.ps1 | iex
  112. ```
  113. Make sure to restart your terminal after installing uv.
  114. 3. **Project Setup**
  115. ```bash
  116. # Clone repository
  117. git clone https://github.com/yourusername/oracle-mcp-server.git
  118. cd oracle-mcp-server
  119. # Create and activate virtual environment
  120. uv venv
  121. # Activate (On Unix/macOS)
  122. source .venv/bin/activate
  123. # Activate (On Windows)
  124. .venv\Scripts\activate
  125. # Install dependencies
  126. uv pip install -e .
  127. ```
  128. 4. **Configure VSCode Settings**
  129. ```json
  130. "mcp": {
  131. "inputs": [
  132. {
  133. "id": "db-password",
  134. "type": "promptString",
  135. "description": "Oracle DB Password",
  136. "password": true,
  137. }
  138. ],
  139. "servers": {
  140. "oracle": {
  141. "command": "/path/to/your/.local/bin/uv",
  142. "args": [
  143. "--directory",
  144. "/path/to/your/oracle-mcp-server",
  145. "run",
  146. "main.py"
  147. ],
  148. "env": {
  149. "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
  150. "TARGET_SCHEMA":"",
  151. "CACHE_DIR":".cache",
  152. "THICK_MODE":"", // Optional: set to "1" to enable thick mode
  153. "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and if you want to set a non-default directory for client libraries
  154. "READ_ONLY_MODE":"1" // Optional: set to "0" to allow write operations (default: "1" for read-only)
  155. }
  156. }
  157. }
  158. }
  159. ```
  160. - Replace the paths with your actual uv binary path and oracle-mcp-server directory path
  161. For both options:
  162. - Replace the `ORACLE_CONNECTION_STRING` with your actual database connection string
  163. - The `TARGET_SCHEMA` is optional, it will default to the user's schema
  164. - The `CACHE_DIR` is optional, defaulting to `.cache` within the MCP server root folder
  165. - The `READ_ONLY_MODE` defaults to "1" (read-only) for security. Set to "0" only when write operations are needed
  166. ### Starting the Server locally
  167. To run the MCP server directly:
  168. ```bash
  169. uv run main.py
  170. ```
  171. For development and testing:
  172. ```bash
  173. # Install the MCP Inspector
  174. uv pip install mcp-cli
  175. # Test with MCP Inspector
  176. mcp dev main.py
  177. # Or install in Claude Desktop
  178. mcp install main.py
  179. ```
  180. ### Available Tools
  181. When connected to an AI assistant like GitHub Copilot in VSCode Insiders or Claude, the following tools will be available:
  182. #### `get_table_schema`
  183. Get detailed schema information for a specific table including columns, data types, nullability, and relationships.
  184. Example:
  185. ```
  186. Can you show me the schema for the EMPLOYEES table?
  187. ```
  188. #### `get_tables_schema`
  189. Get schema information for multiple tables at once. More efficient than calling get_table_schema multiple times.
  190. Example:
  191. ```
  192. Please provide the schemas for both EMPLOYEES and DEPARTMENTS tables.
  193. ```
  194. #### `search_tables_schema`
  195. Search for tables by name pattern and retrieve their schemas.
  196. Example:
  197. ```
  198. Find all tables that might be related to customers and show their schemas.
  199. ```
  200. #### `rebuild_schema_cache`
  201. Force a rebuild of the schema cache. Use sparingly as this is resource-intensive.
  202. Example:
  203. ```
  204. The database structure has changed. Could you rebuild the schema cache?
  205. ```
  206. #### `get_database_vendor_info`
  207. Get information about the connected Oracle database version and schema.
  208. Example:
  209. ```
  210. What Oracle database version are we running?
  211. ```
  212. #### `search_columns`
  213. Search for tables containing columns that match a specific term. Useful when you know what data you need but aren't sure which tables contain it.
  214. Example:
  215. ```
  216. Which tables have columns related to customer_id?
  217. ```
  218. #### `get_pl_sql_objects`
  219. Get information about PL/SQL objects like procedures, functions, packages, triggers, etc.
  220. Example:
  221. ```
  222. Show me all stored procedures that start with 'CUSTOMER_'
  223. ```
  224. #### `get_object_source`
  225. Retrieve the source code for a PL/SQL object. Useful for debugging and understanding database logic.
  226. Example:
  227. ```
  228. Can you show me the source code for the CUSTOMER_UPDATE_PROC procedure?
  229. ```
  230. #### `get_table_constraints`
  231. Get all constraints (primary keys, foreign keys, unique constraints, check constraints) for a table.
  232. Example:
  233. ```
  234. What constraints are defined on the ORDERS table?
  235. ```
  236. #### `get_table_indexes`
  237. Get all indexes defined on a table, helpful for query optimization.
  238. Example:
  239. ```
  240. Show me all indexes on the CUSTOMERS table.
  241. ```
  242. #### `get_dependent_objects`
  243. Find all objects that depend on a specified database object.
  244. Example:
  245. ```
  246. What objects depend on the CUSTOMER_VIEW view?
  247. ```
  248. #### `get_user_defined_types`
  249. Get information about user-defined types in the database.
  250. Example:
  251. ```
  252. Show me all custom types defined in the schema.
  253. ```
  254. #### `get_related_tables`
  255. Get all tables that are related to a specified table through foreign keys, showing both incoming and outgoing relationships.
  256. Example:
  257. ```
  258. What tables are related to the ORDERS table?
  259. ```
  260. #### `run_sql_query`
  261. Execute a SQL query and return the results in a formatted table.
  262. Example:
  263. ```
  264. Can you run this query for me? SELECT * FROM EMPLOYEES WHERE DEPARTMENT_ID = 10
  265. ```
  266. **Note**: In read-only mode (default), only SELECT statements are permitted. Write operations (INSERT, UPDATE, DELETE) are blocked for security. When read-only mode is deactivated (`READ_ONLY_MODE="0"`), this tool can execute both read and write operations.
  267. ## Architecture
  268. This MCP server employs a three-layer architecture optimized for large-scale Oracle databases:
  269. 1. **DatabaseConnector Layer**
  270. - Manages Oracle database connections and query execution
  271. - Implements connection pooling and retry logic
  272. - Handles raw SQL operations
  273. 2. **SchemaManager Layer**
  274. - Implements intelligent schema caching
  275. - Provides optimized schema lookup and search
  276. - Manages the persistent cache on disk
  277. 3. **DatabaseContext Layer**
  278. - Exposes high-level MCP tools and interfaces
  279. - Handles authorization and access control
  280. - Provides schema optimization for AI consumption
  281. ## Connection Modes
  282. The database connector supports two connection modes:
  283. ### Thin Mode (Default)
  284. By default, the connector uses Oracle's thin mode, which is a pure Python implementation. This mode is:
  285. - Easier to set up and deploy
  286. - Sufficient for most basic database operations
  287. - More portable across different environments
  288. ### Thick Mode
  289. For scenarios requiring advanced Oracle features or better performance, you can enable thick mode:
  290. - When using Docker (recommended): Set `THICK_MODE=1` in the Docker environment variables
  291. - When using local installation: Export `THICK_MODE=1` environment variable and ensure Oracle Client libraries, compatible with your system architecture and database version, are installed
  292. You can specify a custom location for the Oracle Client libraries using the `ORACLE_CLIENT_LIB_DIR` environment variable. This is particularly useful when:
  293. - You have Oracle Client libraries installed in non-standard locations
  294. - You need to work with multiple Oracle Client versions on the same system
  295. - You don't have administrative privileges to install Oracle Client in standard locations
  296. - You need specific Oracle Client versions for compatibility with certain database features
  297. Note: When using Docker, you don't need to worry about installing Oracle Client libraries as they are included in the container (Oracle Instant Client v23.7). The container supports Oracle databases versions 19c up to 23ai in both linux/arm64 and linux/amd64 architectures.
  298. ## Read-Only Mode
  299. The MCP server operates in read-only mode by default for increased security. This prevents any write operations (INSERT, UPDATE, DELETE, DDL) while allowing full read access to the database. It protects against unintended changes from AI-generated queries.
  300. ### Configuration
  301. - **Default**: `READ_ONLY_MODE="1"` (read-only, secure)
  302. - **Write Access**: `READ_ONLY_MODE="0"` (allows write operations)
  303. ## System Requirements
  304. - **Python**: Version 3.12 or higher (required for optimal performance)
  305. - **Memory**: 4GB+ available RAM for large databases (10,000+ tables)
  306. - **Disk**: Minimum 500MB free space for schema cache
  307. - **Oracle**: Compatible with Oracle Database 11g and higher
  308. - **Network**: Stable connection to Oracle database server
  309. ## Performance Considerations
  310. - Initial cache building may take 5-10 minutes for very large databases
  311. - Subsequent startups typically take less than 30 seconds
  312. - Schema lookups are generally sub-second after caching
  313. - Memory usage scales with active schema size
  314. ## Contributing
  315. We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
  316. ## License
  317. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  318. ## Support
  319. For issues and questions:
  320. - Create an issue in this GitHub repository

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.