Claude's integration with Oracle Autonomous Transaction Processing (ATP) opens up powerful possibilities for database management and AI-assisted development.
In this comprehensive guide, we'll walk through the step-by-step process of connecting Claude Desktop app to Oracle ATP on macOS, enabling seamless database queries and interactions.
Prerequisites & Architecture Overview
Before we begin, here's how the connection works:
- SQLcl (SQL Command Line) acts as the bridge between Claude and Oracle ATP
- Claude Desktop communicates with SQLcl through an MCP (Model Context Protocol) server
- Wallet files secure the database credentials
Here is the Architecture how we can connect and it works.
First, check if Homebrew is already installed on your Mac:
Open Mac Terminal and run:
If it says command not found:
Then run below:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
It asks for our Mac password and takes a few minutes. Then read the "Next steps" it prints at the end , it tells us to add Homebrew to our PATH, and skipping it is why brew stays "not found" afterward:
echo >> ~/.zprofile echo 'eval "$(/opt/homebrew/bin/brew shellenv zsh)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv zsh)"
Verify the installation:
brew --version
Step 2: Install SQLcl
Run:
brew install --cask sqlcl
verify that SQLcl is available:
sqlcl -vIf you get a Java error, install Java first:
Run Below to install Java:
brew install --cask temurin@21
Then verify Java is installed:
java -version
Now Run the SQLcl version check again:sqlcl -v
Confirm the binary path:
ls -l /opt/homebrew/bin/sqlcl
Step 3: Download and Configure Wallet
The wallet file contains the encrypted credentials needed to connect to Oracle ATP.
Download the Wallet
- Log into the OCI Console
- Navigate to Autonomous Database → Database connection → Download wallet
- Select Instance Wallet
- Set a wallet password (this is separate from your database user password)
Once downloaded Move it somewhere permanent — SQLcl reads it on every connect, so ~/Downloads folder is not a good place for credentials as by mistake sometimes we can delete as well.
Run below commands one by one
mkdir -p ~/oracle/wallets
unzip ~/Downloads/Wallet_devatp.zip -d ~/oracle/wallets/devatp
chmod 700 ~/oracle/wallets/devatp
ls -la ~/oracle/wallets/devatp
Step 4: Identify The Service Name
Run the below command:grep -o '^[a-z0-9_]*' ~/oracle/wallets/devatp/tnsnames.ora | sort -u
We will get devatp_low, devatp_medium, devatp_high, devatp_tp etc.
Step 5: Save The Connection
Launch SQLcl:Run the below command in terminal:sqlcl /nolog
Now in the sql prompt run below, we have used admin user in example, we can use any other DB user as well.The connection will prompt for the database password and save it securely.
conn -save atp_mcp -savepwd admin@devatp_low?TNS_ADMIN=/Users/khusheesumit/oracle/wallets/devatp
Step 6: Verify the Connection
This is the step that predicts whether Claude will work, so don't skip it:
In the sql prompt run below:
conn -name atp_mcp
Now run a test query:
select sys_context('userenv','db_name') from dual;
If this returns your database name, you're good to go. Now test the MCP connection:
Run below in Mac terminal not in sql prompt.
env -i HOME="$HOME" /opt/homebrew/bin/sqlcl -mcp
Silence with no prompt returning is success; it's waiting on stdin for MCP messages. Ctrl+C to exit. Any Java or classpath error here means you need an env block in the config, and you've found it before Claude muddies the diagnosis.
If you see Java or classpath errors, you'll need to add an environment block to Claude's config file later.
The ATP side setup is done. Now lets download and configure the Claude desktop.
Step 7: Download and Configure Claude Desktop
Download Claude Desktop
Visit https://claude.com/download and download the macOS version.
Install and Launch
- Open the DMG file
- Move Claude to your Applications folder
- Launch Claude and sign in with your Google or email account
Step 8: Configure the MCP Server
Now we need to edit the claude_desktop_config.json file to add MCP server so that claude and connect to our ATP database.
Open the Claude Desktop config file:
Run the below in terminal:open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
Alternatively, use Claude's Settings UI:
- Click your profile → Settings → Developer
As shown below
As there are not MCP servers currently added so the file would look like below:
We need to add below line of code,Just after:
"coworkUserFilesPath": "/Users/khusheesumit/Claude",
Or anywhere with the correct syntax and comma.
"mcpServers": {
"sqlcl": {
"command": "/opt/homebrew/bin/sqlcl",
"args": ["-mcp"]
}
}
Our updated file would look like below:
{
"coworkUserFilesPath": "/Users/khusheesumit/Claude",
"mcpServers": {
"sqlcl": {
"command": "/opt/homebrew/bin/sqlcl",
"args": ["-mcp"]
}
},
"preferences": {
"launchPreviewPersistedWorkspaces": [],
"launchPreviewSessionScopedSessions": [],
"coworkScheduledTasksEnabled": true,
"coworkHipaaRestricted": false,
"ccdScheduledTasksEnabled": true,
"sidebarMode": "chat",
"bypassPermissionsGateByAccount": {
"9faa76ab-2958-48f6-adcc-d7012a42fa5e": false
},
"coworkWebSearchEnabled": true,
"coworkModelAutoFallbackByAccount": {
"9faa76ab-2958-48f6-adcc-d7012a42fa5e": true
},
"remoteToolsDeviceName": "macbook-air-local",
"epitaxyPrefs": {
"dframe-group-scopes": {},
"dframe-local-slice": {
"pinnedOrder": [],
"homeProjectsPinnedOrder": []
},
"starred-local-code-sessions": [],
"starred-session-groups": [],
"starred-cowork-spaces": [],
"ccd-sessions-filter": {
"state": {
"selectedProjects": []
},
"version": 0
},
"desktop-frame.paneStore.v1": {
"state": {
"extraPanesByMode": {},
"colWeightsByMode": {},
"rowSplit": 0.5,
"draftNonce": 0
},
"version": 4
}
}
}
}
Make sure your JSON syntax is correct, with proper commas and braces.
Restart Claude Desktop
Quit Claude completely and reopen it. If there are no errors, it should launch smoothly.
Step 9: Verify MCP Connection in Claude
Once Claude restarts:
- Go to your profile → Settings → Developer
- You should see your sqlcl MCP server running
Now let us check if we are able to connect and query something from out ATP database from Claude desktop.
Step 10: Test Your First Database Query
Let's make sure everything works end-to-end.
- Return to the Claude home screen
- Ask Claude to connect to your ATP database using your saved connection name:
atp_mcp
- Claude will prompt you to approve connections—accept these requests
Now as we remember our MCP server is sqlcl and connection anime is atp_mcp which we had saved earlier.
Now let us query the ATP.
use sqlcl mcp server and atp_mcp connection and provide me the tables from the atp which has obj in name
It will prompt below to establish connection:
Keep allowing for all the above requests.
Here is the result.
Now let us fine tune , I have APEX_USER Schema and it has only two tables with OBJ in name. As shown below from sql developer.
So claude also should provide us the same list.
We will ask like below:
Can you share the table list under APEX_USER schema and has OBJ in name?
PERFECT!
Here is the result.
We have Successfully connected and tested our Claude desktop app with our ATP database
using MCP server.
Next Steps
In the next posts we will explore below points.
- Claude Code and SQL Developer extension with VS Code:
- Integrating Claude into our IDE and connecting to ATP from there
- Windows Setup: How to do all this on a Windows machine
No comments:
Post a Comment