home / mcp / oracledb mcp server

OracleDB MCP Server

Provides Oracle DB table/column context for LLMs to generate SQL and retrieve results.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "hemangbhavasar-oracledb_mcp_server": {
      "command": "uv",
      "args": [
        "run",
        "oracledb_mcp_server"
      ],
      "env": {
        "DEBUG": "True",
        "TABLE_WHITE_LIST": "ACCOUNTS,CUS_ACC_RELATIONS,CUSTOMERS",
        "COLUMN_WHITE_LIST": "ACCOUNTS.ACC_AAD_ID,CUS_ACC_RELATIONS.CAR_CUS_ID,CUS_ACC_RELATIONS.CAR_AAD_ID,CUSTOMERS.CUS_ID",
        "DB_CONNECTION_STRING": "oracle+oracledb://USERNAME:PASSWORD@IP:PORT/?service_name=SERVICENAME",
        "COMMENT_DB_CONNECTION_STRING": "oracle+oracledb://USERNAME:PASSWORD@IP:PORT/?service_name=SERVICENAME"
      }
    }
  }
}

OracleDB MCP Server provides configured Oracle Database Tables and Columns as context to large language models, enabling safe SQL generation, execution, and result retrieval through prompts. It lets you expose a curated subset of your Oracle data to LLMs so they can reason with real context while keeping control over what’s accessible.

How to use

Set up your MCP client to include the OracleDB MCP Server as an MCP endpoint. You will run a local stdio MCP server that exposes the Oracle context to your LLM workflow. Use the client configuration to point at the local MCP process and supply the required connection details for your Oracle database. The server reads the context from the whitelisted tables and columns you specify and surfaces it to the LLM for prompt-driven SQL generation and results.

Start the MCP server using the standard runtime command provided in your setup. When you start it, it will listen for requests from your MCP client and supply the Oracle context you configured. In your client, reference the server by the name shown in your config (for example, oracledb_mcp_server) and provide the environment values that control the connection and whitelists.

How to install

Prerequisites: ensure you have Python and a compatible runtime environment installed on your system.

Install the MCP package from Python’s package repository.

pip install oracledb_mcp_server

Create a working folder and place a minimal environment file containing at least your Oracle DB connection string. This enables the MCP server to connect to Oracle during tests and runtime.

# Example .env (minimum value)
DB_CONNECTION_STRING=oracle+oracledb://USERNAME:PASSWORD@IP:PORT/?service_name=SERVICENAME

Test the MCP server by running it with the runtime command shown in your setup from the folder that contains your .env.

uv run oracledb_mcp_server

Additional configuration and notes

Configuration for the MCP client often mirrors a structured config snippet that defines the MCP server under mcpServers. You typically specify the command to run the server and the arguments needed to start it, along with environment variables that control debugging and access to the Oracle database.

{
  "mcpServers": {
    "oracledb_mcp_server":{
      "command": "uv",
      "args": ["run","oracledb_mcp_server"],
      "env": {
        "DEBUG":"True",
        "COMMENT_DB_CONNECTION_STRING":"oracle+oracledb://USERNAME:PASSWORD@IP:PORT/?service_name=SERVICENAME",
        "DB_CONNECTION_STRING":"oracle+oracledb://USERNAME:PASSWORD@IP:PORT/?service_name=SERVICENAME",
        "TABLE_WHITE_LIST":"ACCOUNTS,CUS_ACC_RELATIONS,CUSTOMERS",
        "COLUMN_WHITE_LIST":"ACCOUNTS.ACC_AAD_ID,CUS_ACC_RELATIONS.CAR_CUS_ID,CUS_ACC_RELATIONS.CAR_AAD_ID,CUSTOMERS.CUS_ID"
      }
    }
  }
}

Available tools

provide_context

Expose configured Oracle tables and columns as contextual data to the LLM so it can reference real-world values in prompts.

generate_sql

Assist in crafting SQL statements based on natural language prompts using the provided Oracle context.

execute_sql

Execute generated SQL against the Oracle database and return results to the LLM workflow.

return_results

Return query results and context to the user or downstream components of the MCP workflow.