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
| 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/tiger@192.168.1.10: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).