My Complete Local Oracle 26ai + Claude Desktop Setup

ny2honolulu — August 21, 2026 AI & Agents, Database, Development Environment

Overview

A fully local Oracle development environment where:

• Claude Desktop talks to your Oracle database using natural language (via MCP)
• SQL Developer provides a classic visual GUI for the same database
• Both tools share the same connection and the same running database

1. Core Components

Component	Version / Details	Purpose
Oracle Database Free	26ai (23.26.3.0.0) via Docker (container-registry.oracle.com/database/free)	The actual database
SQLcl	26.2.1	Command-line tool + MCP Server
Claude Desktop	Unofficial Linux package (claude-desktop-unofficial)	AI assistant that talks to the DB
SQL Developer	26.2.0	Visual GUI tool

2. Step-by-Step Setup

A. Install SQLcl

bash

mkdir -p ~/oracle-tools && cd ~/oracle-tools
curl -L -o sqlcl-latest.zip https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip
unzip sqlcl-latest.zip
echo 'export PATH="$HOME/oracle-tools/sqlcl/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

B. Start Oracle Database Free (Docker)

bash

docker run -d \
  --name oracle26ai \
  -p 1521:1521 \
  -e ORACLE_PWD=YourStrongPassword123 \
  container-registry.oracle.com/database/free:latest

Wait until logs show: DATABASE IS READY TO USE!

Check status any time with:

bash

docker ps

Look for STATUS: Up (healthy) next to oracle26ai.

C. Create saved connection in SQLcl

bash

sql /nolog

sql

conn -save my_mcp -savepwd system/YourStrongPassword123@//localhost:1521/FREEPDB1
exit

D. Start MCP Server

bash

sql -mcp

E. Configure Claude Desktop

Edit: ~/.config/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "sqlcl": {
      "command": "/home/<your-username>/oracle-tools/sqlcl/bin/sql",
      "args": ["-mcp"]
    }
  }
  // ... (keep your existing preferences)
}

Note: Replace <your-username> with the actual username on the machine you’re configuring — this differs between machines (e.g. lvydvy on desktop vs ny2honolulu on the HP laptop). Use whoami to confirm before editing.

Restart Claude Desktop → Settings → Developer → confirm sqlcl is running.

F. Connect SQL Developer (GUI)

New Connection:

• Name: my_mcp
• Username: system
• Password: YourStrongPassword123 (Save Password)
• Hostname: localhost
• Port: 1521
• Service name: FREEPDB1 (not SID)

Test → Save → Connect

3. How the Two Tools Work Together

Tool	Role	How it talks to the database
Claude Desktop	Natural language AI	Uses the SQLcl MCP Server
SQL Developer	Visual GUI	Direct JDBC connection to the same database

They share:

• The same Docker container (oracle26ai)
• The same connection name (my_mcp)
• The same credentials (system / YourStrongPassword123)

You can use both at the same time with no conflict.

4. Useful Daily Commands

bash

# Start database (if stopped)
docker start oracle26ai

# Start MCP server manually
sql -mcp

# Launch Claude
claude-desktop-unofficial

# Launch SQL Developer
sqldeveloper

5. Installing SQL Developer via alien (Debian)

If you’re on Debian and need to install SQL Developer from Oracle’s RPM-only Linux release:

bash

# 1. Confirm Java is installed (17+)
java -version

# 2. Install alien and dependencies
sudo apt update && sudo apt install alien dpkg-dev debhelper build-essential

# 3. Download the RPM directly
cd ~/Downloads
wget https://download.oracle.com/otn_software/java/sqldeveloper/sqldeveloper-26.2.0-186.2220.noarch.rpm

# 4. Convert to .deb
sudo alien --to-deb --scripts sqldeveloper-26.2.0-186.2220.noarch.rpm

# 5. Install the .deb
sudo dpkg -i sqldeveloper_26.2.0-187.222_all.deb

# 6. Launch (first run prompts for JDK path)
sqldeveloper

When prompted for JDK path, use the output of:

bash

update-alternatives --list java

(drop the trailing /bin/java, e.g. /usr/lib/jvm/java-21-openjdk-amd64)