nikhilpawar9/oracle-mcp-server

Oracle MCP Server

A basic Model Context Protocol (MCP) server for Oracle database operations built with Node.js.

Features

• Execute SQL queries against Oracle database
• List database tables
• Describe table structure and columns
• Secure connection handling with environment variables

Prerequisites

• Node.js (v18 or higher)
• Oracle Database (local or remote)
• Oracle Instant Client (for the oracledb package)

Installation

1. Install dependencies:

npm install

2. Copy the environment configuration:

cp env.example .env

3. Update the .env file with your Oracle database credentials:

ORACLE_USER=your_username
ORACLE_PASSWORD=your_password
ORACLE_CONNECTION_STRING=localhost:1521/XE

Oracle Instant Client Setup

The oracledb package requires Oracle Instant Client. Follow these steps:

Windows

1. Download Oracle Instant Client from Oracle's website
2. Extract to a directory (e.g., C:\oracle\instantclient_21_8)
3. Add the directory to your PATH environment variable

macOS

# Using Homebrew
brew install instantclient-basic

Linux

# Download and install Oracle Instant Client
wget https://download.oracle.com/otn_software/linux/instantclient/219000/instantclient-basic-linux.x64-21.9.0.0.0dbru.zip
unzip instantclient-basic-linux.x64-21.9.0.0.0dbru.zip
sudo mv instantclient_21_9 /opt/oracle/
export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_9:$LD_LIBRARY_PATH

Usage

Running the Server

# Start the server
npm start

# Or run in development mode with auto-restart
npm run dev

Available Tools

The server provides the following MCP tools:

1. execute_query: Execute SQL queries

   • Parameters: query (required), params (optional array)

2. get_tables: List database tables

   • Parameters: owner (optional schema name)

3. describe_table: Get table column information

   • Parameters: tableName (required), owner (optional schema name)

Example Usage

Once connected to an MCP client, you can use these tools:

• Execute a simple query: execute_query with query: "SELECT * FROM employees WHERE department = 'IT'"
• List all tables: get_tables
• Describe a table: describe_table with tableName: "employees"

Connection String Examples

• Local Oracle XE: localhost:1521/XE
• Oracle Cloud: your_host:1521/your_service_name
• TNS: (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service_name)))

Security Notes

• Never commit your .env file to version control
• Use environment variables for sensitive database credentials
• Consider using Oracle Wallet for production deployments

License

ISC