MCP HubMCP Hub
danielmeppiel

mcp-db-context

by: danielmeppiel

MCP Server for working with large Oracle databases

22created 14/03/2025
Visit
Oracle
database

📌Overview

Purpose: To provide AI assistants with accurate and relevant contextual database schema information for large Oracle databases, avoiding information overload.

Overview: The MCP Oracle DB Context server addresses the complex challenge of managing vast Oracle databases by intelligently caching and serving schema information. This allows AI tools to efficiently access and utilize database structures and relationships without overwhelming processing capabilities.

Key Features:

  • Smart Schema Caching: Minimizes database queries by maintaining a local cache of database schema information.

  • Targeted Schema Lookup: Enables retrieval of schema details for specific tables, improving efficiency by not loading the entire database structure.

  • Table Search: Facilitates finding tables based on name patterns, enhancing ease of access to relevant data.

  • Relationship Mapping: Provides insights into foreign key relationships between tables, aiding in the understanding of data connections.

  • Oracle Database Support: Specifically developed to work seamlessly with Oracle databases.

  • MCP Integration: Compatible with popular AI assistants, including GitHub Copilot in VSCode, enhancing functionality for developers.

MCP Server - Oracle DB Context

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.

Table of Contents

  • Overview
  • Features
  • Usage
    • Integration with GitHub Copilot in VSCode Insiders
      • Option 1: Using Docker (Recommended)
      • Option 2: Using UV (Local Installation)
    • Starting the Server locally
    • Available Tools
  • Architecture
  • Connection Modes
    • Thin Mode (Default)
    • Thick Mode
  • System Requirements
  • Performance Considerations
  • Contributing
  • License
  • Support

Overview

The MCP Oracle DB Context server addresses the challenge of providing AI models with accurate, relevant database schema information without overwhelming them with thousands of tables and relationships.

By intelligently caching and serving database schema information, this server allows AI assistants to:

  • Look up specific table schemas on demand
  • Search for tables that match specific patterns
  • Understand table relationships and foreign keys
  • Get database vendor information

Features

  • Smart Schema Caching: Builds and maintains a local cache of your database schema to minimize database queries
  • Targeted Schema Lookup: Retrieve schema for specific tables without loading the entire database structure
  • Table Search: Find tables by name pattern matching
  • Relationship Mapping: Understand foreign key relationships between tables
  • Oracle Database Support: Built specifically for Oracle databases
  • MCP Integration: Works seamlessly with GitHub Copilot in VSCode, Claude, ChatGPT, and other AI assistants that support MCP

Usage

Integration with GitHub Copilot in VSCode Insiders

To use this MCP server with GitHub Copilot in VSCode Insiders, follow these steps:

  1. Install VSCode Insiders

    • Download and install the latest version of VSCode Insiders

  2. Install GitHub Copilot Extension

    • Open VSCode Insiders
    • Go to the Extensions marketplace
    • Search for and install "GitHub Copilot"

  3. Configure MCP Server

    • Recommended: Using Docker (see below)
    • Alternative: Using UV (local installation, see below)

  4. Enable Agent Mode

    • Open Copilot chat in VSCode Insiders
    • Click on "Copilot Edits"
    • Choose "Agent mode"
    • Click the refresh button in the chat input to load the available tools

After completing these steps, you'll have access to all database context tools through GitHub Copilot's chat interface.

Option 1: Using Docker (Recommended)

In VSCode Insiders, add the following to your user or workspace settings.json:

"mcp": {
    "inputs": [
     {
       "id": "db-password",
       "type": "promptString",
       "description": "Oracle DB Password",
       "password": true
     }
   ],
    "servers": {
        "oracle": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "ORACLE_CONNECTION_STRING",
                "-e",
                "TARGET_SCHEMA",
                "-e",
                "CACHE_DIR",
                "-e",
                "THICK_MODE",
                "dmeppiel/oracle-mcp-server"
            ],
            "env": {
               "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
               "TARGET_SCHEMA":"",
               "CACHE_DIR":".cache",
               "THICK_MODE":""
            }
        }
    }
}

Notes:

  • All dependencies are included in the container.
  • Set THICK_MODE=1 in the environment variables to enable thick mode if needed.

Option 2: Using UV (Local Installation)

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

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

Restart your terminal after installing UV.

  1. Project Setup
git clone https://github.com/yourusername/oracle-mcp-server.git
cd oracle-mcp-server

uv venv

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

# Activate virtual environment (Windows)
.venv\Scripts\activate

uv pip install -e .
  1. Configure VSCode Settings
"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":""
            }
      }
   }
}

Replace paths with your actual uv binary path and oracle-mcp-server directory.

For both options:

  • Replace the ORACLE_CONNECTION_STRING with your actual connection string.
  • TARGET_SCHEMA is optional and defaults to the user's schema.
  • CACHE_DIR defaults to .cache within the MCP server root folder.

Starting the Server locally

Run the MCP server directly:

uv run main.py

For development and testing:

uv pip install mcp-cli

mcp dev main.py

# Or install in Claude Desktop
mcp install main.py

Available Tools

When connected to an AI assistant like GitHub Copilot or Claude, these tools are available:

  • get_table_schema: Get schema for a specific table.
  • get_tables_schema: Get schema for multiple tables.
  • search_tables_schema: Search tables by name pattern.
  • rebuild_schema_cache: Force rebuild of schema cache (resource-intensive).
  • get_database_vendor_info: Get the connected Oracle database version.
  • search_columns: Search tables by column names.
  • get_pl_sql_objects: Retrieve info about PL/SQL objects.
  • get_object_source: Get source code for a PL/SQL object.
  • get_table_constraints: Get constraints on a table.
  • get_table_indexes: Get indexes on a table.
  • get_dependent_objects: Find objects dependent on a specified object.
  • get_user_defined_types: Info about user-defined types.
  • get_related_tables: Tables related through foreign keys.

Architecture

The MCP server uses a three-layer architecture optimized for large-scale Oracle databases:

  1. DatabaseConnector Layer
    Manages Oracle connections, query execution, connection pooling, and retry logic.

  2. SchemaManager Layer
    Implements schema caching, optimized lookups, and manages persistent cache on disk.

  3. DatabaseContext Layer
    Exposes high-level MCP tools, manages authorization, and optimizes schema for AI.

Connection Modes

Thin Mode (Default)

  • Uses Oracle's pure Python thin mode driver.
  • Easier to set up and deploy.
  • Suitable for most basic operations.
  • More portable.

Thick Mode

  • Enables advanced Oracle features and better performance.
  • Docker: Set THICK_MODE=1 environment variable.
  • Local install: Set THICK_MODE=1 and install Oracle Client libraries matching your architecture and database version.

Note: Docker containers include Oracle Instant Client v23.7 and support Oracle DB 19c to 23ai on linux/arm64 and linux/amd64.

System Requirements

  • Python 3.12 or higher
  • 4GB+ RAM recommended for large databases
  • Minimum 500MB free disk space for schema cache
  • Compatible with Oracle Database 11g and later
  • Stable network connection to Oracle server

Performance Considerations

  • Initial schema cache building: 5–10 minutes on large databases
  • Subsequent startups: under 30 seconds
  • Schema lookups: typically sub-second after cache built
  • Memory usage depends on active schema size

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

License

Licensed under the MIT License.

Support

For issues and questions, create an issue in this GitHub repository.