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/[email protected]:1521/XEPDB1
admin/[email protected]: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

| Variable | Default | Description | |---|---|---| | ORACLE_CONNECTION | (required) | Full connection string | | SQLPLUS_PATH | sqlplus | Path to sqlplus binary if not in PATH | | QUERY_TIMEOUT_MS | 30000 | Query timeout in milliseconds |

Custom sqlplus path example

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

Available Tools

| Tool | Description | |---|---| | test_connection | Test connectivity and return Oracle version | | list_schemas | List all schemas with table counts | | list_tables | List tables, optionally filtered by schema or name pattern | | describe_table | Show columns, data types, nullable, primary keys | | get_table_sample | Fetch sample rows from a table | | execute_query | Run any SELECT query | | execute_ddl | Run DDL/DML (INSERT, UPDATE, DELETE, CREATE, etc.) | | list_procedures | List stored procedures, functions, packages |

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