Oracle Database Model Context Protocol Server
raw JSON →The `mcp-oracle-database` package provides a Model Context Protocol (MCP) server specifically designed to enable AI assistants, such as GitHub Copilot, to execute read-only SQL queries against Oracle databases. Currently at version `1.0.0`, it offers a stable initial release. While no explicit release cadence is stated, its design as a crucial bridge for LLM-driven database interactions suggests ongoing maintenance. Key differentiators include its strict read-only access model for enhanced security, direct standard input/output (stdio) transport for communication (eliminating the need for an HTTP server), efficient Oracle connection pooling, and capabilities for schema introspection. It also features audit logging for all executed queries, timeout protection for long-running operations, and configurable row limits to prevent excessive memory usage. Notably, it leverages `node-oracledb` in Thin Mode, which means developers do not need to install the Oracle Instant Client, simplifying deployment and setup compared to traditional Oracle database drivers.
Common errors
error Failed to start MCP Oracle Database Server process: Error: spawn mcp-database-server ENOENT ↓
npm install -g mcp-oracle-database was successful and your PATH includes npm's global bin directory. If installed locally: Ensure npm install mcp-oracle-database was run and you are invoking the command correctly, e.g., via npx mcp-database-server or by specifying the full path node_modules/.bin/mcp-database-server. error Error: ORA-12170: TNS:Connect timeout occurred ↓
ORACLE_CONNECTION_STRING environment variable is correct (hostname, port, service name/SID). Ensure the Oracle database instance is running and is accessible from the machine hosting the MCP server (check network connectivity and firewall rules). error Error: ORA-01017: invalid username/password; logon denied ↓
ORACLE_USER and ORACLE_PASSWORD environment variables contain the correct credentials for your read-only Oracle user. Ensure the user has CONNECT privilege on the database. Warnings
gotcha The `mcp-oracle-database` server explicitly uses `node-oracledb` in 'Thin Mode', which means it *does not* require the traditional Oracle Instant Client installation. Developers accustomed to other Oracle drivers might mistakenly attempt to install Instant Client, leading to unnecessary complexity or confusion. ↓
gotcha Security relies heavily on configuring a dedicated, restricted read-only Oracle database user. Granting excessive privileges to the user configured in `ORACLE_USER` can undermine the server's read-only security model, potentially allowing write operations if the LLM generates them. ↓
gotcha Incorrectly configured environment variables (e.g., `ORACLE_CONNECTION_STRING`, `ORACLE_USER`, `ORACLE_PASSWORD`) are the leading cause of server startup failures or inability to connect to the database. These variables are critical for establishing a connection. ↓
gotcha The `QUERY_TIMEOUT_MS` and `MAX_ROWS_PER_QUERY` environment variables directly control query execution limits. Setting these values too high can lead to long-running, resource-intensive queries that consume excessive database resources or server memory, potentially causing performance degradation or Out-of-Memory (OOM) errors. ↓
Install
npm install mcp-oracle-database yarn add mcp-oracle-database pnpm add mcp-oracle-database Imports
- startServer
import { startServer } from 'mcp-oracle-database'; - OracleMcpServerConfig
import type { OracleMcpServerConfig } from 'mcp-oracle-database'; - OracleDatabaseError
import { OracleDatabaseError } from 'mcp-oracle-database';
Quickstart
import { spawn } from 'child_process';
import * as path from 'path';
// Define the environment variables for the MCP server
// For production, use a secure method to manage credentials.
const env = {
ORACLE_CONNECTION_STRING: process.env.ORACLE_CONNECTION_STRING ?? 'localhost:1521/XEPDB1',
ORACLE_USER: process.env.ORACLE_USER ?? 'your_readonly_user',
ORACLE_PASSWORD: process.env.ORACLE_PASSWORD ?? 'your_password',
ORACLE_POOL_MIN: process.env.ORACLE_POOL_MIN ?? '2',
ORACLE_POOL_MAX: process.env.ORACLE_POOL_MAX ?? '10',
QUERY_TIMEOUT_MS: process.env.QUERY_TIMEOUT_MS ?? '30000',
MAX_ROWS_PER_QUERY: process.env.MAX_ROWS_PER_QUERY ?? '1000',
// Inherit current process environment to ensure basic PATH, etc.
...process.env,
};
// The executable command as installed via npm -g or in node_modules/.bin
const command = 'mcp-database-server';
console.log(`Attempting to start MCP Oracle Database Server with command: ${command}`);
console.log('Ensure ORACLE_CONNECTION_STRING, ORACLE_USER, ORACLE_PASSWORD are set via environment variables.');
// Spawn the server process, similar to how an MCP client would
const serverProcess = spawn(command, [], {
env,
stdio: ['pipe', 'pipe', 'pipe'], // Capture stdin, stdout, stderr
});
serverProcess.stdout.on('data', (data) => {
console.log(`[Server stdout]: ${data.toString().trim()}`);
});
serverProcess.stderr.on('data', (data) => {
console.error(`[Server stderr]: ${data.toString().trim()}`);
});
serverProcess.on('close', (code) => {
console.log(`MCP Oracle Database Server process exited with code ${code}`);
});
serverProcess.on('error', (err) => {
console.error(`Failed to start MCP Oracle Database Server process: ${err.message}`);
});
// In a real scenario, an MCP client would then write JSON-RPC messages to serverProcess.stdin.
// For example, to send an 'initialize' message after a delay:
/*
setTimeout(() => {
const initializeMessage = {
jsonrpc: '2.0',
id: 1,
method: 'initialize',
params: { capabilities: {} }
};
console.log('Sending simulated MCP initialize message...');
serverProcess.stdin.write(JSON.stringify(initializeMessage) + '\n');
}, 5000);
*/
// Keep the Node.js process alive for a bit to see output (optional)
setTimeout(() => {
if (!serverProcess.killed) {
console.log('Simulated parent process exit after 60 seconds.');
serverProcess.kill(); // Terminate the child process
}
}, 60000);