A Model Context Protocol (MCP) server for Oracle Database, enabling AI assistants like Cursor to execute SQL statements directly against Oracle databases. Oracle trademark, database, and Instant Client are properties of the Oracle company, they are not part of this solution.
stdin mcp service for Cursor connect Oracle database
Full SQL support: SELECT, INSERT, UPDATE, DELETE, DDL (CREATE, DROP, ALTER, etc.), and multiple statements per request
Execute from file: Run a full SQL file via execute_sql_file; trailing SQL*Plus / is stripped automatically
Query to file: query_to_csv_file (result as CSV, RFC 4180, UTF-8) and query_to_text_file (plain text, tab-separated, CLOB in full; e.g. for procedure source)
PL/SQL blocks: CREATE PROCEDURE/FUNCTION/PACKAGE (including files with leading comments) and anonymous blocks are executed as one unit
Human-in-the-loop review UI: Configurable danger keywords trigger a review window with full SQL. The Keywords area shows the actual expanded identifiers that triggered review (for example created_at, not just create)
Whitelist review bypass: Allow Header saves the SQL first line to whitelist.json and skips future review for the same connection + header line
Whitelist keyword filtering: Allow Keyword saves a keyword to whitelist.json without approving the current review; future matches remove only that specific expanded keyword trigger, while other unmatched dangerous triggers still open review
Whitelist keyword guardrails: review UI only accepts whitelist keywords made of letters, numbers, and underscores, and blocks values that exactly match danger_keywords (case-insensitive)
Danger keyword matching: whole_text (substring in full SQL) or tokens (exact token match; e.g. created_at does not match create)
Multi-database: Configure multiple connections; use list_connections to see names and status (failed connections are retried on each list; only list_connections re-validates—other tools fast-fail on an unavailable connection until you call it again)
Audit logging: Keyed fields (AUDIT_TIME, AUDIT_CONNECTION, AUDIT_KEYWORDS, AUDIT_APPROVED, AUDIT_ACTION, AUDIT_SQL) plus whitelist context such as HEADER_LINE and EXPANDED_KEYWORDS; full SQL, record separator ######AUDIT_END######; 10MB rotation, reuse last non-full file on startup, filenames include creation date (e.g. audit_2006-01-02_150405.log)
Connection security: Database connection strings (including passwords) in config.yaml are automatically encrypted on first startup — no manual steps required
Cross-platform review UI: Windows (WinForms + WebBrowser) and macOS (JXA/Cocoa dialog) both support Allow Keyword, Allow Header, Execute, and Cancel
Single executable: Standalone binary (requires Oracle Instant Client)
Copy config.yaml.example to config.yaml and configure at least one connection under oracle.connections:
oracle:
connections:
database1: "user/pass@//host:1521/ORCL"
# database2: "user/pass@//host2:1521/ORCL"
security:
# "whole_text" = substring in full SQL; "tokens" = exact token match (e.g. created_at ≠ create)
danger_keyword_match: "whole_text"
danger_keywords:
- truncate
- drop
- delete
- create
- update
- execute immediate
# ... (see config.yaml.example)
require_confirm_for_ddl: true # DDL always requires confirmation
logging:
audit_log: true
verbose_logging: true # One short stderr line per execute_sql / execute_sql_file
log_file: "audit.log" # Base name; actual files: audit_YYYY-MM-DD_HHMMSS.log, 10MB rotation
With one connection, all SQL runs against that database (no need to pass connection). With multiple connections, use the connection argument in execute_sql / execute_sql_file and list_connections to see names and availability.
Multiple security profiles: define named profiles under security_profiles (same fields as security; omitted fields use built-in defaults) and bind connections to them with oracle.connection_security. Connections not listed use the top-level security section (profile name default, which can also be referenced explicitly). Unknown profile or connection names are rejected at startup.
Connection security: On first startup, any plain-text connection strings in config.yaml are automatically replaced with encrypted values. The file is updated in place — comments and formatting are preserved.
Environment Variables
Variable
Description
ORACLE_MCP_CONFIG
Path to config file (overrides default locations)
ORACLE_HOME
Oracle client installation path
PATH (Windows)
Must include Instant Client directory
TNS_ADMIN
Required for Oracle Autonomous Database (ADB) — directory containing tnsnames.ora and wallet files (e.g. cwallet.sso, ewallet.pem, sqlnet.ora) from the ADB Wallet zip
Oracle Autonomous Database (ADB) with Wallet
ADB uses TCPS (SSL) and requires the Wallet. Use the TNS name from the wallet’s tnsnames.ora (e.g. mcpdemo_high):
Download Wallet: Oracle Cloud Console → your Autonomous Database → DB connection → Download Wallet. Unzip to a folder (e.g. D:\oracle\wallet_mcpdemo). The folder must contain tnsnames.ora, sqlnet.ora, cwallet.sso, ewallet.pem, etc.
config.yaml — use TNS alias and your DB user/password:
Cursor MCP — set TNS_ADMIN to the Wallet directory so the process can find tnsnames.ora and SSL certs. On Windows, also include Instant Client in PATH:
Replace D:\oracle\wallet_mcpdemo with your unzipped wallet path, and ensure Instant Client is on PATH. Without TNS_ADMIN, you may see ORA-12541 (no listener) or SSL errors because the client cannot resolve the TNS name or use the wallet.
Usage with Cursor
MCP Configuration
Add to your Cursor MCP settings (~/.cursor/mcp.json or workspace .cursor/mcp.json):
Replace /path/to/oracle-mcp and /opt/oracle/instantclient_19_20 with your actual paths. You can also reference existing shell env with "ORACLE_HOME": "${env:ORACLE_HOME}" if Cursor was started from a terminal that already has it set.
Tools
Tool
Description
execute_sql
Run SQL (one or multiple statements). Params: sql, optional connection. Do not specify schema-qualified object names such as hr.employees; the server rejects them.
execute_sql_file
Read SQL from a file, analyze, show review if needed, then execute. Trailing / is stripped. Params: file_path, optional connection. SQL in the file must not specify schema-qualified object names such as hr.employees.
list_connections
List configured connection names and availability; retries previously failed connections (only this tool re-validates—others fast-fail on unavailable connection until you call list_connections again).
query_to_csv_file
Run a query and write the result to a file as CSV (header + rows, UTF-8, RFC 4180). Params: sql, file_path (absolute), optional connection. Same review as execute_sql when SQL matches danger keywords or DDL (if enabled). Do not specify schema-qualified object names such as hr.employees.
query_to_text_file
Run a query and write the result to a file as plain text (tab-separated, no header; CLOB in full; e.g. for procedure source). Params: sql, file_path (absolute), optional connection. Same review as execute_sql when SQL matches danger keywords or DDL (if enabled). Do not specify schema-qualified object names such as hr.employees.
Example Interactions
// One connection: no need to pass connection
execute_sql({ "sql": "SELECT table_name FROM user_tables" })
// Multiple connections
execute_sql({ "sql": "SELECT * FROM my_table", "connection": "database1" })
execute_sql({ "sql": "CREATE TABLE test (id NUMBER)", "connection": "database2" })
// Run a SQL file (e.g. procedure script; trailing / stripped)
execute_sql_file({ "file_path": "d:\\scripts\\myscript.sql", "connection": "ps" })
// See connection names and status
list_connections()
// Write query result to CSV or text file (file_path must be absolute; same review rules as execute_sql when needed)
query_to_csv_file({ "sql": "SELECT * FROM my_table", "file_path": "d:\\out\\data.csv", "connection": "database1" })
query_to_text_file({ "sql": "SELECT text FROM user_source WHERE name='MY_PROC'", "file_path": "d:\\out\\my_proc.sql" })
Safety and Review Window
When SQL matches danger_keywords or is DDL (if require_confirm_for_ddl is true), a confirmation window appears:
Keywords display: the review header shows the actual expanded identifiers that triggered review, not just the original configured danger keyword
Allow Header: stores the current SQL first line in whitelist.json; future SQL on the same connection with the same first line skips review
Allow Keyword: stores one keyword in whitelist.json but does not approve the current review; users can add multiple keywords before choosing Execute or Cancel
Keyword whitelist behavior: a whitelisted keyword removes only that specific expanded-keyword trigger; if the same SQL still has other dangerous unmatched triggers, review still opens
Whitelist storage: whitelist.json is stored in the executable directory / program directory
Windows: WinForms window with syntax-highlighted SQL (WebBrowser)
macOS: JXA/Cocoa dialog with the same review actions as Windows
Execution proceeds only after the user confirms. Rejection is logged and returned as USER_REJECTED.
SQL Execution
Single statement: One SQL statement, with or without trailing semicolon.
Multiple statements: One per line, each line ending with a semicolon. Executed in order.
PL/SQL: CREATE PROCEDURE/FUNCTION/PACKAGE (including files with leading -- or /* */) and anonymous blocks (BEGIN...END; / DECLARE...END;) are treated as one block and not split.
From file: Trailing SQL*Plus / (on its own line) is removed before execution.
Audit Log
Keyed format: AUDIT_TIME=..., AUDIT_CONNECTION=..., AUDIT_KEYWORDS=..., AUDIT_APPROVED=..., AUDIT_ACTION=..., optional HEADER_LINE=..., optional EXPANDED_KEYWORDS=..., then AUDIT_SQL= followed by the full SQL, then a line ######AUDIT_END###### as record separator.
Rotation: 10MB per file. On startup, the most recent existing log file under 10MB is reused; when full, a new file is created with creation date in the name: audit_2006-01-02_150405.log.
MCP Protocol
Tool: execute_sql
Input: sql (required), connection (optional). Do not specify schema-qualified object names such as hr.employees; the server rejects them.
Input: file_path (required), connection (optional). Same analysis and review rules as execute_sql; executes the file contents (trailing / stripped).
Tool: list_connections
Input: none. Output: connections (name + availability), message. Only this tool re-validates failed connections; other tools return an error if the chosen connection is currently unavailable until you call list_connections again.
Tool: query_to_csv_file
Input: sql (required), file_path (required, absolute path), connection (optional). Output: success and path. Same confirmation rules as execute_sql when SQL matches danger_keywords or is DDL (if require_confirm_for_ddl). Writes CSV with header, UTF-8, RFC 4180; CLOB columns read in full.
Tool: query_to_text_file
Input: sql (required), file_path (required, absolute path), connection (optional). Output: success and path. Same confirmation rules as execute_sql when SQL matches danger_keywords or is DDL (if require_confirm_for_ddl). Writes plain text, tab-separated columns, no header; CLOB in full (e.g. for procedure source).
Troubleshooting
Connection Issues
Error: ORA-12541: TNS:no listener
→ Check that Oracle Instant Client is in PATH and listener is running
Error: DPI-1047: Cannot locate a 64-bit Oracle Client library
→ Install Oracle Instant Client and add to PATH
Permission Issues
Error: ORA-01031: insufficient privileges
→ The configured database user lacks required permissions
Building from Source (optional)
If you prefer to build the binary yourself (e.g. for a different Go version or platform):
Build dependencies
Go 1.22+
CGO must be enabled: godror requires CGO and a C compiler.
Windows: Use MinGW-w64 (GCC 7.2+) and add its bin to PATH.
Do not use Cygwin's gcc. If both are installed, ensure MinGW's bin comes before Cygwin in PATH, or you may see cannot parse gcc output ... as ELF, Mach-O, PE, XCOFF.
Install via Chocolatey: choco install mingw, or MSYS2 then pacman -S mingw-w64-ucrt-x86_64-gcc and use mingw64\bin.
Verify with where gcc and gcc -v; you should see "mingw" or "MinGW" and 64-bit (x86_64).
macOS: Run xcode-select --install for command line tools.
Build commands
Important: Build with CGO enabled and GCC available, or you will see errors like undefined: VersionInfo.
# Clone the repository
git clone https://github.com/kjstart/cursor_oracle_mcp_server
cd cursor_oracle_mcp_server
# Download dependencies
go mod tidy
# Windows (PowerShell): enable CGO and ensure gcc is in PATH
$env:CGO_ENABLED="1"
go build -o oracle-mcp.exe .
# Windows (CMD)
set CGO_ENABLED=1
go build -o oracle-mcp.exe .
# Windows (MSYS UCRT64)
export PATH=/c/oracle/instantclient_21_12:$PATH
export ORACLE_HOME=/c/oracle/instantclient_21_12
pacman -S mingw-w64-ucrt-x86_64-go
export GOROOT=/ucrt64/lib/go
export PATH=$GOROOT/bin:$PATH
export CGO_ENABLED=1
export CC=x86_64-w64-mingw32-gcc
go install github.com/godror/godror@latest
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 go build -o oracle-mcp.exe .
# macOS (Intel): native build only
CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o oracle-mcp .
# macOS (Apple Silicon)
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o oracle-mcp .
Build troubleshooting
Error
Cause
Fix
undefined: VersionInfo
CGO disabled
Set CGO_ENABLED=1 and install gcc
gcc not found
gcc not installed or not in PATH
Install MinGW-w64 and add its bin to PATH
cannot parse gcc output ... as ELF, Mach-O, PE, XCOFF
Wrong gcc (e.g. Cygwin gcc)
Use MinGW-w64 gcc and put it before Cygwin in PATH; verify with where gcc and gcc -v
After changing gcc or PATH, clear the build cache and rebuild: