Oracle Database Model Context Protocol Server

raw JSON →
1.0.0 verified Thu Apr 23 auth: no javascript

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.

error Failed to start MCP Oracle Database Server process: Error: spawn mcp-database-server ENOENT
cause The `mcp-database-server` executable could not be found in the system's PATH or `node_modules/.bin`.
fix
If installed globally: Ensure 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
cause The Oracle database server could not be reached at the specified connection string within the timeout period.
fix
Verify that the 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
cause The provided Oracle username or password in the environment variables is incorrect or the user does not have sufficient privileges to connect.
fix
Confirm that 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.
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.
fix No action required. The package handles Oracle connectivity purely in JavaScript. Ensure you have Node.js v18 or higher.
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.
fix Always create a specific Oracle user with only `CONNECT` and `SELECT` privileges on the necessary tables/schemas. Regularly audit user privileges and avoid using administrator or write-enabled accounts for the server.
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.
fix Double-check all Oracle-related environment variables for typos, correct host/port/service name, and valid credentials. Ensure the Oracle database is running and accessible from the server's host machine. Consult your Oracle DBA for connection string specifics.
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.
fix Configure `QUERY_TIMEOUT_MS` and `MAX_ROWS_PER_QUERY` to reasonable, conservative values that align with typical query expectations and available server resources. Start with lower values and increase only if necessary, monitoring performance.
npm install mcp-oracle-database
yarn add mcp-oracle-database
pnpm add mcp-oracle-database

Demonstrates how to programmatically spawn and monitor the MCP Oracle Database server process using TypeScript, mimicking its execution via a VS Code MCP client configuration. It shows how environment variables configure database connection details and how to capture server output.

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);