oradb-explorer-mcp

An MCP server and skills package for read-only Oracle exploration using node-oracledb 7 in Thin mode.

Download the repository

Windows PowerShell:

git clone https://github.com/YOUR_USER/oradb-explorer-mcp.git
Set-Location oradb-explorer-mcp

macOS/Linux:

git clone https://github.com/YOUR_USER/oradb-explorer-mcp.git
cd oradb-explorer-mcp

Setup

Windows PowerShell:

npm install
Copy-Item .env.example .env

macOS/Linux:

npm install
cp .env.example .env

Windows .env:

ORACLE_USER=your_user
ORACLE_PASSWORD=your_password
ORACLE_DSN=your_connect_string
# Optional: used only if the normal Thin-mode connection fails
ORACLE_WALLET_LOCATION=C:\secure\adb-wallet

macOS/Linux .env:

ORACLE_USER=your_user
ORACLE_PASSWORD=your_password
ORACLE_DSN=your_connect_string
# Optional: used only if the normal Thin-mode connection fails
ORACLE_WALLET_LOCATION=/home/your-user/adb-wallet

Never commit the real .env file.

Start locally

Windows and macOS/Linux:

npx tsx mcp/server.ts

The server uses MCP stdio and normally produces no terminal output.

Codex MCP configuration

Windows:

[mcp_servers.oradb]
command = 'C:\path\to\oradb-explorer-mcp\node_modules\.bin\tsx.cmd'
args = ['C:\path\to\oradb-explorer-mcp\mcp\server.ts']
env = { ORACLE_ENV_FILE = '.env' }
startup_timeout_sec = 30
tool_timeout_sec = 120

macOS/Linux:

[mcp_servers.oradb]
command = '/path/to/oradb-explorer-mcp/node_modules/.bin/tsx'
args = ['/path/to/oradb-explorer-mcp/mcp/server.ts']
env = { ORACLE_ENV_FILE = '.env' }
startup_timeout_sec = 30
tool_timeout_sec = 120

Available tools

oradb_connect
oradb_status
oradb_disconnect
oradb_tables
oradb_describe
oradb_indexes
oradb_sql_preview
oradb_run_readonly_sql
oradb_dataframe_preview
oradb_dataframe_export

Natural-language workflow

The MCP server does not use Select AI or generate SQL inside the database. The host agent interprets the user’s natural-language request and generates a candidate SQL statement. The MCP server validates and executes it safely.

Recommended workflow:

1. User describes the desired analysis.
2. The agent generates one read-only SELECT or WITH statement.
3. The agent calls oradb_sql_preview.
4. The SQL and bind values are reviewed.
5. The agent calls oradb_run_readonly_sql with a row limit.

Example request:

Find the five most recent active customers and return their ID, name,
status, and registration date.

The agent may generate:

SELECT customer_id, name, status, registration_date
FROM customers
WHERE status = :status
ORDER BY registration_date DESC
FETCH FIRST 5 ROWS ONLY

with binds:

{
  "status": "ACTIVE"
}

Schema exploration examples

List tables whose names start with CUSTOM.

Describe the CUSTOMERS table.

List indexes on APP_SCHEMA.CUSTOMERS.

Dataframe examples

Preview selected columns:

Preview CUSTOMER_ID, NAME, and STATUS from CUSTOMERS, limited to 20 rows.

Export a bounded result to a user-selected file:

Export CUSTOMER_ID, NAME, and STATUS from CUSTOMERS to
/tmp/customers.csv using oradb_dataframe_export.

Windows example:

Export CUSTOMER_ID, NAME, and STATUS from CUSTOMERS to
C:\\temp\\customers.csv using oradb_dataframe_export.

Supported formats are CSV and JSON. The result can then be consumed by pandas, Polars, or marimo without overwhelming the agent context.

Safety boundary

The server allows one bounded SELECT or WITH statement. It rejects semicolon-separated statements and does not provide DDL, DML, PL/SQL, commit, privilege, or credential-management tools.

Credentials, wallet files, database dumps, and generated artifacts must remain outside Git.