{"id":17791,"library":"mcp-oracle-database","title":"Oracle Database Model Context Protocol Server","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/tannerpace/my-mcp","tags":["javascript","mcp","model-context-protocol","database","sql","copilot","github-copilot","ai","llm","typescript"],"install":[{"cmd":"npm install mcp-oracle-database","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-oracle-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-oracle-database","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"startServer","correct":"import { startServer } from 'mcp-oracle-database';"},{"note":"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.","symbol":"OracleMcpServerConfig","correct":"import type { OracleMcpServerConfig } from 'mcp-oracle-database';"},{"note":"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.","symbol":"OracleDatabaseError","correct":"import { OracleDatabaseError } from 'mcp-oracle-database';"}],"quickstart":{"code":"import { spawn } from 'child_process';\nimport * as path from 'path';\n\n// Define the environment variables for the MCP server\n// For production, use a secure method to manage credentials.\nconst env = {\n  ORACLE_CONNECTION_STRING: process.env.ORACLE_CONNECTION_STRING ?? 'localhost:1521/XEPDB1',\n  ORACLE_USER: process.env.ORACLE_USER ?? 'your_readonly_user',\n  ORACLE_PASSWORD: process.env.ORACLE_PASSWORD ?? 'your_password',\n  ORACLE_POOL_MIN: process.env.ORACLE_POOL_MIN ?? '2',\n  ORACLE_POOL_MAX: process.env.ORACLE_POOL_MAX ?? '10',\n  QUERY_TIMEOUT_MS: process.env.QUERY_TIMEOUT_MS ?? '30000',\n  MAX_ROWS_PER_QUERY: process.env.MAX_ROWS_PER_QUERY ?? '1000',\n  // Inherit current process environment to ensure basic PATH, etc.\n  ...process.env,\n};\n\n// The executable command as installed via npm -g or in node_modules/.bin\nconst command = 'mcp-database-server';\n\nconsole.log(`Attempting to start MCP Oracle Database Server with command: ${command}`);\nconsole.log('Ensure ORACLE_CONNECTION_STRING, ORACLE_USER, ORACLE_PASSWORD are set via environment variables.');\n\n// Spawn the server process, similar to how an MCP client would\nconst serverProcess = spawn(command, [], {\n  env,\n  stdio: ['pipe', 'pipe', 'pipe'], // Capture stdin, stdout, stderr\n});\n\nserverProcess.stdout.on('data', (data) => {\n  console.log(`[Server stdout]: ${data.toString().trim()}`);\n});\n\nserverProcess.stderr.on('data', (data) => {\n  console.error(`[Server stderr]: ${data.toString().trim()}`);\n});\n\nserverProcess.on('close', (code) => {\n  console.log(`MCP Oracle Database Server process exited with code ${code}`);\n});\n\nserverProcess.on('error', (err) => {\n  console.error(`Failed to start MCP Oracle Database Server process: ${err.message}`);\n});\n\n// In a real scenario, an MCP client would then write JSON-RPC messages to serverProcess.stdin.\n// For example, to send an 'initialize' message after a delay:\n/*\nsetTimeout(() => {\n  const initializeMessage = {\n    jsonrpc: '2.0',\n    id: 1,\n    method: 'initialize',\n    params: { capabilities: {} }\n  };\n  console.log('Sending simulated MCP initialize message...');\n  serverProcess.stdin.write(JSON.stringify(initializeMessage) + '\\n');\n}, 5000);\n*/\n\n// Keep the Node.js process alive for a bit to see output (optional)\nsetTimeout(() => {\n  if (!serverProcess.killed) {\n    console.log('Simulated parent process exit after 60 seconds.');\n    serverProcess.kill(); // Terminate the child process\n  }\n}, 60000);","lang":"typescript","description":"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."},"warnings":[{"fix":"No action required. The package handles Oracle connectivity purely in JavaScript. Ensure you have Node.js v18 or higher.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`.","cause":"The `mcp-database-server` executable could not be found in the system's PATH or `node_modules/.bin`.","error":"Failed to start MCP Oracle Database Server process: Error: spawn mcp-database-server ENOENT"},{"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).","cause":"The Oracle database server could not be reached at the specified connection string within the timeout period.","error":"Error: ORA-12170: TNS:Connect timeout occurred"},{"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.","cause":"The provided Oracle username or password in the environment variables is incorrect or the user does not have sufficient privileges to connect.","error":"Error: ORA-01017: invalid username/password; logon denied"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}