Oracle DB MCP Server
A Model Context Protocol (MCP) server for Oracle Database connectivity. This server enables AI tools like Cursor, Claude Desktop, and other MCP-compatible clients to interact with Oracle databases.
Features
- Multiple Database Connections: Configure and manage multiple named Oracle database connections
- Thin & Thick Mode Support: Works with Oracle's thin driver (no client required) or thick mode (with Oracle Instant Client)
- Query Execution: Execute SELECT queries with result formatting
- DML Operations: Execute INSERT, UPDATE, DELETE with safety checks
- PL/SQL Support: Execute PL/SQL blocks, create procedures/functions
- Schema Browsing: List tables, views, procedures, describe table structures
- Stored Procedures: Execute stored procedures with input/output parameters
- Transaction Management: Commit and rollback support
- Safety Features: Read-only mode, dangerous query detection, automatic warnings
Installation
Using npx (Recommended)
No installation required. Configure your MCP client to run:
npx -y oracle-db-mcp
Local Installation
npm install -g oracle-db-mcp
Then run:
oracle-db-mcp
Configuration
Configuration File (connections.json)
Create a configuration file with your database connections:
{
"oracleClient": {
"mode": "thin"
},
"settings": {
"defaultMaxRows": 100,
"queryTimeout": 30
},
"connections": [
{
"name": "dev",
"host": "dev-server.company.com",
"port": 1521,
"serviceName": "DEVDB",
"username": "dev_user",
"password": "dev_password",
"mode": "readwrite"
},
{
"name": "prod",
"host": "prod-server.company.com",
"port": 1521,
"serviceName": "PRODDB",
"username": "report_user",
"passwordEnv": "PROD_DB_PASSWORD",
"mode": "readonly"
}
]
}
Connection Options
Each connection supports:
| Option | Description |
|---|---|
name | Unique identifier for the connection |
host | Database server hostname |
port | Port number (default: 1521) |
serviceName | Oracle service name |
sid | Oracle SID (alternative to serviceName) |
connectionString | Full connection string (alternative to host/port/service) |
username | Database username |
password | Database password (direct) |
passwordEnv | Environment variable containing password |
mode | readonly or readwrite |
Configuration File Locations
The server searches for configuration in this order:
ORACLE_MCP_CONFIGenvironment variable./config/connections.json./connections.json~/.oracle-mcp/connections.json
Environment Variables
For simple single-connection setup:
export ORACLE_CONNECTION_NAME=mydb
export ORACLE_HOST=localhost
export ORACLE_PORT=1521
export ORACLE_SERVICE=XEPDB1
export ORACLE_USER=scott
export ORACLE_PASSWORD=tiger
export ORACLE_MODE=readonly
MCP Client Configuration
Cursor
Add to your Cursor MCP settings (.cursor/mcp.json):
{
"mcpServers": {
"oracle-db": {
"command": "npx",
"args": ["-y", "oracle-db-mcp"],
"env": {
"ORACLE_MCP_CONFIG": "/path/to/connections.json"
}
}
}
}
Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"oracle-db": {
"command": "npx",
"args": ["-y", "oracle-db-mcp"],
"env": {
"ORACLE_MCP_CONFIG": "/path/to/connections.json"
}
}
}
}
Available Tools
Connection Management
| Tool | Description |
|---|---|
list_connections | List all configured connections with status |
test_connection | Test connectivity and get database info |
connect | Establish a connection |
disconnect | Close a connection |
Query Execution
| Tool | Description |
|---|---|
execute_query | Execute SELECT queries |
execute_dml | Execute INSERT/UPDATE/DELETE |
execute_plsql | Execute PL/SQL blocks or DDL |
execute_procedure | Call stored procedures |
Schema Browsing
| Tool | Description |
|---|---|
list_tables | List tables and views |
describe_table | Get column, constraint, index info |
list_procedures | List procedures, functions, packages |
get_procedure_source | Get source code of PL/SQL objects |
get_procedure_params | Get procedure parameters |
explain_query | Get query execution plan |
Transaction Management
| Tool | Description |
|---|---|
commit | Commit current transaction |
rollback | Rollback current transaction |
Safety Features
Read-Only Mode
Connections configured as readonly:
- Block all DML operations (INSERT, UPDATE, DELETE)
- Block PL/SQL execution
- Allow only SELECT queries
Dangerous Query Detection
The server warns or blocks:
- DROP statements
- TRUNCATE statements
- UPDATE/DELETE without WHERE clause
- ALTER SYSTEM commands
Oracle Client Modes
Thin Mode (Default)
No Oracle client installation required. Works with:
- Oracle Database 12.1 and later
- Oracle Cloud databases
Thick Mode
Requires Oracle Instant Client. Enable in config:
{
"oracleClient": {
"mode": "thick",
"path": "/path/to/instantclient"
}
}
Required for:
- Oracle Database versions before 12.1
- Advanced features (LDAP, Kerberos, etc.)
- Some data types (BFILE, etc.)
Development
Building from Source
git clone https://github.com/titan213/oracle-db-mcp
cd oracle-db-mcp
npm install
npm run build
Running in Development
npm run dev
Testing
npm test
License
MIT
Author
Gihan Sundarapperuma gihan213@gmail.com
