Skip to main content
Glama
oracle-db-mcp

oracle-db-mcp

by Kuass

oracle-db-mcp

Model Context Protocol server to access oracle

Python 3.12 PyPI - Version License: MIT

Note: This repository is based on hdcola/mcp-server-oracle. Original work by hdcola.

Quickstart

Prerequisites

  • Python 3.12+ or Docker

  • Claude Desktop or other MCP client

  • Oracle Database connection credentials

Installation

Choose one of the following methods:

uvx oracle-db-mcp

Option 2: Using pipx

pipx install oracle-db-mcp

Option 3: Using Docker

docker pull ghcr.io/kuass/oracle-db-mcp

Configuration

Add the server configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Using uvx

{
  "mcpServers": {
    "oracle-db-mcp": {
      "command": "uvx",
      "args": [
        "oracle-db-mcp"
      ],
      "env": {
        "ORACLE_CONNECTION_STRING": "username/password@hostname:port/service_name"
      }
    }
  }
}

Using pipx

{
  "mcpServers": {
    "oracle-db-mcp": {
      "command": "oracle-db-mcp",
      "args": [],
      "env": {
        "ORACLE_CONNECTION_STRING": "username/password@hostname:port/service_name"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "oracle-db-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ORACLE_CONNECTION_STRING",
        "ghcr.io/kuass/oracle-db-mcp"
      ],
      "env": {
        "ORACLE_CONNECTION_STRING": "username/password@hostname:port/service_name"
      }
    }
  }
}

The Docker image automatically remaps localhost to work from inside the container:

  • MacOS/Windows: Uses host.docker.internal

  • Linux: Uses the host IP address

Using uv (Development)

{
  "mcpServers": {
    "oracle-db-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/oracle-db-mcp",
        "oracle-db-mcp"
      ],
      "env": {
        "ORACLE_CONNECTION_STRING": "username/password@hostname:port/service_name"
      }
    }
  }
}

Thick Mode (Optional)

By default, the server uses Thin mode which doesn't require Oracle Client installation. To use Thick mode:

{
  "mcpServers": {
    "oracle-db-mcp": {
      "command": "uvx",
      "args": [
        "oracle-db-mcp"
      ],
      "env": {
        "ORACLE_CONNECTION_STRING": "username/password@hostname:port/service_name",
        "ORACLE_THICK_MODE": "true",
        "ORACLE_CLIENT_LIB_DIR": "/path/to/oracle/instantclient"
      }
    }
  }
}

Related MCP server: Mini Oracle MCP Server

SSE Transport

Oracle MCP supports Server-Sent Events (SSE) transport, allowing multiple MCP clients to share one server.

Start SSE Server

Using Docker

docker run -p 8000:8000 \
  -e ORACLE_CONNECTION_STRING="username/password@hostname:port/service_name" \
  ghcr.io/kuass/oracle-db-mcp --transport=sse

Using uvx

ORACLE_CONNECTION_STRING="username/password@hostname:port/service_name" \
  uvx oracle-db-mcp --transport=sse

Configure MCP Client

For Cursor or Cline (mcp.json or cline_mcp_settings.json):

{
  "mcpServers": {
    "oracle-db-mcp": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

For Windsurf (mcp_config.json):

{
  "mcpServers": {
    "oracle-db-mcp": {
      "type": "sse",
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}

Available Tools

Schema Exploration

  • list_tables: Get a list of all tables in the database

  • list_schemas: Get a list of all schemas in the database

  • list_objects: List database objects (tables, views, sequences, packages) in a schema

  • get_object_details: Get detailed information about a database object (columns, constraints, indexes)

  • describe_table: Get detailed information about a table

Query Execution

  • read_query: Execute SELECT queries

  • exec_dml_sql: Execute INSERT/UPDATE/DELETE/TRUNCATE statements

  • exec_ddl_sql: Execute CREATE/DROP/ALTER statements

  • exec_pro_sql: Execute PL/SQL code blocks

Performance Analysis

  • get_top_queries: Get the slowest queries based on elapsed time

  • explain_query: Get the execution plan for a SQL query

  • analyze_db_health: Perform comprehensive database health checks (tablespace usage, session status, wait events, invalid objects)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

12 tools
analyze_db_healthB

Perform comprehensive database health checks including tablespace usage, session status, wait events, and invalid objects

Args:
    include_all_invalid (bool, optional): If True, return all invalid objects. If False, limit to first 20. Default is False

Inputs: include_all_invalid.

describe_tableC

Get a description of a table in the oracle database"

Args:
    table_name (string): The name of the table to describe

Inputs: table_name (required).

exec_ddl_sqlC

Execute create/drop/alter to the oracle database

Args:
    query (string): The sql to execute

Inputs: execsql (required).

exec_dml_sqlC

Execute insert/update/delete/truncate to the oracle database

Args:
    query (string): The sql to execute

Inputs: execsql (required).

exec_pro_sqlC

Execute PL/SQL code blocks including stored procedures, functions and anonymous blocks

Args:
    execsql (string): The PL/SQL code block to execute

Inputs: execsql (required).

explain_queryC

Get the execution plan for a SQL query

Args:
    query (string): The SQL query to explain

Inputs: query (required).

get_object_detailsC

Get detailed information about a database object

Args:
    object_name (string): The name of the object
    object_type (string, optional): The type of object (TABLE, VIEW, SEQUENCE). Default is TABLE

Inputs: object_name (required), object_type.

get_top_queriesB

Get the slowest queries based on elapsed time

Args:
    limit (int, optional): Number of queries to return. Default is 10

Inputs: limit.

list_objectsA

List database objects (tables, views, sequences, packages) in a schema

Args:
    schema_name (string, optional): The schema name to list objects from. If not provided, lists objects from current user's schema
    object_type (string, optional): Filter by object type (TABLE, VIEW, SEQUENCE, PACKAGE, FUNCTION, PROCEDURE)
    limit (int, optional): Maximum number of objects to return. Default is 100

Inputs: limit, object_type, schema_name.

list_schemasB

Get a list of all schemas in the oracle database

Args:
    None

Inputs: no named parameters.

list_tablesB

Get a list of all tables in the oracle database with optional filtering and pagination

Args:
    pattern (string, optional): Filter tables by name pattern (case-insensitive)
    limit (int, optional): Maximum number of tables to return. Default is 50
    offset (int, optional): Number of tables to skip. Default is 0

Inputs: limit, offset, pattern.

read_queryB

Execute SELECT queries to read data from the oracle database

Args:
    query (string): The SELECT query to execute
    max_rows (int, optional): Maximum number of rows to return. Default is 100

Inputs: query (required), max_rows.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, especially the SQL execution family (read_query, exec_dml_sql, exec_ddl_sql, exec_pro_sql) which is well separated by SQL type. However, describe_table overlaps with get_object_details when object_type=TABLE, and list_tables overlaps with list_objects using object_type=TABLE; descriptions help but misselection is possible.

    Naming Consistency4/5

    All tool names use snake_case and a verb_noun pattern, which is consistent. The exec_* prefix uses an abbreviation while other tools use full verbs (get, list, read, describe, explain, analyze), a minor deviation.

    Tool Count5/5

    12 tools is well within the ideal 3-15 range for a database server, and each tool covers a distinct operation or SQL category. No obvious redundancy or bloat.

    Completeness4/5

    Core CRUD and lifecycle operations are covered: listing schemas/tables/objects, describing tables, reading and executing DML/DDL/PL/SQL, explaining queries, and health checks. Minor gaps include index/constraint introspection and explicit transaction control, but agents can likely work around these.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that connects to Oracle databases using sqlplus, enabling SQL queries, schema exploration, and DDL/DML execution through natural language.
      8
      19 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Oracle Database enabling AI assistants to explore schemas, run queries, write data, and monitor sessions via natural language. Features read-only mode by default and uses Oracle Thin mode for zero-install connectivity.
      10
      161 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A production-grade MCP server for Oracle database interaction, providing 11 tools for full CRUD, transactions, execution plans, and comprehensive safety guardrails.
      11
      MIT