oracle-sqlplus-mcp

An MCP (Model Context Protocol) server for Oracle Database using sqlplus as the connection backend. No Oracle Instant Client Node.js bindings required — just a working sqlplus binary.

Prerequisites

• sqlplus must be installed and available in PATH (comes with Oracle Instant Client or full Oracle client)

• Node.js 18+

Installation

npm install -g oracle-sqlplus-mcp
# or run directly with npx (no install needed):
npx oracle-sqlplus-mcp

Connection String Format

username/password@host:port/servicename

Examples:

scott/tiger@localhost:1521/ORCL
myuser/mypass@192.168.1.10:1521/XEPDB1
admin/secret@db.example.com:1521/PROD

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "oracle": {
      "command": "npx",
      "args": ["-y", "oracle-sqlplus-mcp"],
      "env": {
        "ORACLE_CONNECTION": "username/password@host:port/servicename"
      }
    }
  }
}

Optional Environment Variables

Custom sqlplus path example

{
  "mcpServers": {
    "oracle": {
      "command": "npx",
      "args": ["-y", "oracle-sqlplus-mcp"],
      "env": {
        "ORACLE_CONNECTION": "scott/tiger@192.168.1.10:1521/ORCL",
        "SQLPLUS_PATH": "C:\\oracle\\instantclient_21_9\\sqlplus.exe",
        "QUERY_TIMEOUT_MS": "60000"
      }
    }
  }
}

Available Tools

Example Prompts

• "Test the Oracle connection"

• "List all schemas in the database"

• "Show me tables in the SCOTT schema"

• "Describe the EMPLOYEES table"

• "Get 5 sample rows from HR.EMPLOYEES"

• "Run this query: SELECT * FROM departments WHERE department_id < 50"

• "List all stored procedures in the HR schema"

Troubleshooting

sqlplus: command not found

Set SQLPLUS_PATH to the full path of your sqlplus binary.

ORA-12541: TNS:no listener

Check host, port, and that Oracle listener is running.

ORA-01017: invalid username/password

Verify credentials. Connection string format: user/pass@host:port/service.

SP2-0306: Invalid option

Ensure sqlplus version supports -S silent mode (all modern versions do).