Registry / database / mcp-oracle-database

mcp-oracle-database

JSON →
library1.0.0jsnpmunverified

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.

npm install mcp-oracle-database
INSTALL
IMPORT
SIG · MCP-ORACLE-DATABAS
M
mcp-oracle-database
databasejavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer
import { startServer } from 'mcp-oracle-database';
While primarily designed to be run as an executable via a command (e.g., by an MCP client like VS Code), it is plausible that a programmatic entry point like `startServer` is exported for advanced integration or testing, given that the package ships TypeScript types.
OracleMcpServerConfig
import type { OracleMcpServerConfig } from 'mcp-oracle-database';
This type would represent the structure for configuring the Oracle Database MCP server, typically derived from environment variables. Useful for type-checking custom host environments or programmatic setup, as the package ships TypeScript types.
OracleDatabaseError
import { OracleDatabaseError } from 'mcp-oracle-database';
Assuming the server exports custom error classes for database-specific issues, allowing for more granular error handling if interacting with the server programmatically. Primary interaction is via CLI, so direct import is less common for end-users.

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);
Debug
Known issues
gotchaThe `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.
affects: >=1.0.0
gotchaSecurity 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.
affects: >=1.0.0
gotchaIncorrectly 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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
Failed to start MCP Oracle Database Server process: Error: spawn mcp-database-server ENOENT
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: ORA-12170: TNS:Connect timeout occurred
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: ORA-01017: invalid username/password; logon denied
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.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
21 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources