Oracle Mcp Server

[English](#english) | [中文](#chinese)

New Project: Cursor DB MCP

Supports connecting to any database via JDBC. 👉https://github.com/kjstart/cursordb_mcp

---

Oracle MCP Server

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.

Alvin Liu — https://alvinliu.com · Project: https://github.com/kjstart/cursororaclemcpserver

🎬 Demo Video

👉 Click the image below to watch on YouTube [](https://www.youtube.com/watch?v=3U1nWj9tP24)

Features

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

Requirements

Runtime Dependencies

1. Oracle Instant Client

• Download from Oracle website
• Version 19c or later recommended
• Required files: oci.dll, oraociei19.dll (Windows) or equivalent .dylib (macOS)

1. Environment Setup

```bash # Windows: Add Instant Client to PATH set PATH=C:\path\to\instantclient;%PATH%

# macOS: Set library path export DYLDLIBRARYPATH=/path/to/instantclient:$DYLDLIBRARYPATH ```

Installation

Download pre-built binary (recommended)

Pre-built binaries are published on GitHub Releases. No build required.

1. Download the archive for your platform:

• Windows: oracle-mcp-server-windows-amd64-.zip
• macOS Apple Silicon (M1/M2/M3): oracle-mcp-server-darwin-arm64-.tar.gz
• macOS Intel: oracle-mcp-server-darwin-amd64-.tar.gz

1. Extract the archive. You will get:

• The executable (e.g. oracle-mcp-server-windows-amd64.exe or oracle-mcp-server-darwin-arm64)
• user_guide.md — step-by-step setup
• config.yaml.example — copy to config.yaml and edit

1. Install Oracle Instant Client (see [Requirements](#requirements) above) and add it to PATH (Windows) or set ORACLE_HOME and DYLD_LIBRARY_PATH (macOS).

1. Configure config.yaml with your database connection(s), then add the server to Cursor MCP (see [Configuration](#configuration) and [Usage with Cursor](#usage-with-cursor) below).

For a full walkthrough, see [userguide.md](userguide.md).

Configuration

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.

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

1. 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.
2. config.yaml — use TNS alias and your DB user/password:

``yaml oracle: connections: mcpdemo: "mcpdemo/YourPassword@mcpdemo_high" ``

1. 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:

``json { "mcpServers": { "oracle": { "command": "D:\\work\\code\\cursor_oracle_mcp_server\\oracle-mcp.exe", "args": [], "env": { "TNS_ADMIN": "D:\\oracle\\wallet_mcpdemo", "PATH": "C:\\path\\to\\instantclient;%PATH%" } } } } ` Replace D:\oracle\walletmcpdemo with your unzipped wallet path, and ensure Instant Client is on PATH. Without TNSADMIN`, 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):

Windows:

Windows, add Oracle client to PATH

{
  "mcpServers": {
    "oracle": {
      "command": "C:\\path\\to\\oracle-mcp.exe",
      "args": []
    }
  }
}

Mac

Use the env block so the MCP process sees ORACLE_HOME and DYLD_LIBRARY_PATH:

{
  "mcpServers": {
    "oracle": {
      "command": "/path/to/oracle-mcp",
      "args": [],
      "env": {
        "ORACLE_HOME": "/opt/oracle/instantclient_19_20",
        "DYLD_LIBRARY_PATH": "/opt/oracle/instantclient_19_20"
      }
    }
  }
}

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 | |------|-------------| | executesql | 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. | | executesqlfile | 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. | | listconnections | List configured connection names and availability; retries previously failed connections (only this tool re-validates—others fast-fail on unavailable connection until you call listconnections again). | | querytocsvfile | 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. | | querytotext_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.

Output (query): columns, rows, statement_type, execution_time_ms, success.

Output (DML/DDL): rows_affected, statement_type, execution_time_ms, success, optional warning.

Error (user rejected): code -32000, message "Execution cancelled by user", data.code "USER_REJECTED", data.matched_keywords.

Tool: execute_sql_file

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 ma

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kjstart
• Source: kjstart/oraclemcp_server
• License: MIT

Install and usage instructions live in the source repository linked above.