mapeg-oracle-mcp 1.0.0

Oracle Database MCP server for Model Context Protocol

Oracle MCP Server

A Model Context Protocol (MCP) server for Oracle databases. Query, explore, and analyze your Oracle databases directly from any MCP-compatible AI client. Supports Oracle 11g through 23ai with automatic version detection.

Features

• Execute SQL — Run any Oracle SQL with automatic result formatting
• Schema Tools — Describe tables, search columns, view indexes and constraints
• Source Code — Read PL/SQL functions, procedures, packages, and triggers
• Execution Plans — EXPLAIN PLAN via DBMS_XPLAN with configurable detail levels
• Relationships — Foreign key analysis with incoming/outgoing direction filtering
• DBMS_OUTPUT — Automatic capture of PL/SQL output with buffer management
• Query History — Review past queries scoped to your database and workspace
• Auto Version Detection — Detects Oracle version (11g–23ai) dynamically
• Thin Mode — No Oracle Instant Client required
• Read-Only Mode — Optional write protection via READ_ONLY=true

Quick Start

Claude Code

claude mcp add oracle \
  -e ORACLE_CONNECTION_STRING="User Id=myuser;Password=mypass;Data Source=host:1521/service" \
  -- uvx mapeg-oracle-mcp

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oracle": {
      "command": "uvx",
      "args": ["mapeg-oracle-mcp"],
      "env": {
        "ORACLE_CONNECTION_STRING": "User Id=myuser;Password=mypass;Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)))"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "oracle": {
      "command": "uvx",
      "args": ["mapeg-oracle-mcp"],
      "env": {
        "ORACLE_CONNECTION_STRING": "User Id=myuser;Password=mypass;Data Source=host:1521/service"
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config:

{
  "mcpServers": {
    "oracle": {
      "command": "uvx",
      "args": ["mapeg-oracle-mcp"],
      "env": {
        "ORACLE_CONNECTION_STRING": "User Id=myuser;Password=mypass;Data Source=host:1521/service"
      }
    }
  }
}

VS Code

Add to your VS Code settings (JSON):

"mcp": {
  "servers": {
    "oracle": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mapeg-oracle-mcp"],
      "env": {
        "ORACLE_CONNECTION_STRING": "User Id=myuser;Password=mypass;Data Source=host:1521/service"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "oracle": {
      "command": "uvx",
      "args": ["mapeg-oracle-mcp"],
      "env": {
        "ORACLE_CONNECTION_STRING": "User Id=myuser;Password=mypass;Data Source=host:1521/service"
      }
    }
  }
}

GitHub Copilot

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "oracle": {
      "command": "uvx",
      "args": ["mapeg-oracle-mcp"],
      "env": {
        "ORACLE_CONNECTION_STRING": "User Id=myuser;Password=mypass;Data Source=host:1521/service"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.oracle]
command = "uvx"
args = ["mapeg-oracle-mcp"]

[mcp_servers.oracle.env]
ORACLE_CONNECTION_STRING = "User Id=myuser;Password=mypass;Data Source=host:1521/service"

Install from Source

cd mapeg-oracle-mcp
pip install -e .

Configuration

Environment Variable	Required	Default	Description
ORACLE_CONNECTION_STRING	Yes	—	Connection string: User Id=...;Password=...;Data Source=...
READ_ONLY	No	false	Block write operations (INSERT, UPDATE, DELETE, DROP, etc.)

Connection String Format

User Id=USERNAME;Password=PASSWORD;Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service)))

Or the short form:

User Id=USERNAME;Password=PASSWORD;Data Source=hostname:1521/service_name

Tools

execute_sql — Run SQL queries

Execute any SQL query on the connected Oracle database. Supports SELECT, DML, DDL, and PL/SQL blocks with automatic DBMS_OUTPUT capture.

Parameter	Type	Required	Description
sql	string	Yes	Oracle SQL query
limit	integer	No	Max rows to return (default: 100)

describe_table — Table structure details

Get column definitions and row count from USER_TAB_COLUMNS.

Parameter	Type	Required	Description
table_name	string	Yes	Table name (case-insensitive)

get_source_code — Read PL/SQL source

Retrieve source code for functions, procedures, packages, and triggers.

Parameter	Type	Required	Description
object_name	string	Yes	Object name (case-insensitive)
object_type	string	No	FUNCTION, PROCEDURE, TRIGGER, PACKAGE, PACKAGE BODY

get_view_definition — View SQL definition

Get the SQL definition of an Oracle view from USER_VIEWS.

Parameter	Type	Required	Description
view_name	string	Yes	View name (case-insensitive)

search_tables — Search tables by pattern

Find tables matching a name pattern.

Parameter	Type	Required	Description
pattern	string	Yes	Search pattern (supports % wildcard)
limit	integer	No	Max results (default: 100)

search_columns — Search columns across tables

Find columns matching a pattern, optionally filtered by data type.

Parameter	Type	Required	Description
pattern	string	Yes	Column name pattern (supports % wildcard)
data_type	string	No	Filter by data type (e.g., VARCHAR2)
limit	integer	No	Max results (default: 100)

get_table_indexes — Index information

List all indexes on a table with column details.

Parameter	Type	Required	Description
table_name	string	Yes	Table name (case-insensitive)

get_table_constraints — Constraint details

Get primary keys, foreign keys, unique and check constraints.

Parameter	Type	Required	Description
table_name	string	Yes	Table name (case-insensitive)
constraint_type	string	No	Filter: P (PK), R (FK), C (Check), U (Unique)

analyze_table_size — Table size and statistics

Row count, average row length, block count, and size in MB.

Parameter	Type	Required	Description
table_name	string	Yes	Table name (case-insensitive)

get_table_relationships — Foreign key relationships

Analyze incoming and outgoing foreign key relationships.

Parameter	Type	Required	Description
table_name	string	Yes	Table name (case-insensitive)
direction	string	No	incoming, outgoing, or both (default: both)

list_database_objects — List objects by type

List tables, views, functions, procedures, packages, triggers, sequences, or indexes.

Parameter	Type	Required	Description
object_type	string	Yes	TABLE, VIEW, FUNCTION, PROCEDURE, PACKAGE, TRIGGER, SEQUENCE, INDEX
pattern	string	No	Name pattern filter (supports % wildcard)
limit	integer	No	Max results (default: 100)

explain_plan — Execution plan analysis

Generate execution plans using EXPLAIN PLAN and DBMS_XPLAN.

Parameter	Type	Required	Description
sql	string	Yes	SQL query to explain
format	string	No	Detail level: basic, typical, all (default: typical)

get_query_history — Review past queries

Retrieve recent query history scoped to this database and workspace.

Parameter	Type	Required	Description
limit	integer	No	Number of entries (default: 20)
status	string	No	Filter: success or error
tool_name	string	No	Filter by tool name

Resources

URI	Description
oracle://tables	List all user tables
oracle://schema	Table columns from USER_TAB_COLUMNS
oracle://stats	Database version and instance info

License

MIT