Claude Desktop & SQLcl MCP server

When setting up SQLcl MCP server with Claude desktop, the official Oracle instructions give a basic guide.

basically they are saying you need to open the claude_desktop_config.json file in a text editor, and add a JSON configuration snippet in the following format. Replace PATH/bin/sql with the absolute path of your SQLcl installation, and save the configuration file.

{
  "mcpServers": {
    "sqlcl": {
      "command": "PATH/bin/sql",
      "args": ["-mcp"]
    }
  }
}

This however is not sufficient for recent versions of Claude Desktop. In addition, the official instructions don't show you exactly where to paste this snippet.

The error I was getting was:

Exception in thread "main" java.io.UncheckedIOException: java.io.IOException: Unable to establish loopback connection

and this was caused by

java.net.SocketException: Invalid argument: connect
    at sun.nio.ch.UnixDomainSockets.connect0(Native Method)

The root cause is that Claude Desktop runs in a sandbox. When SQLcl starts, JAVA needs to create an internal communication pipe. It does this by writing a tiny temporary file to disk ; but the sandbox blocks access to the default temp folder, so Java can't create that file, and crashes. The fix is pointing Java to C:\Temp, a folder completely outside the sandbox that it's allowed to write to.

So in the fix below, you have to create the c:\temp folder if you don't already have it.

Then you step two is to update your config with the block below.

"mcpServers": {
  "sqlcl": {
    "command": "C:/Oracle/sqlcl/bin/sql",
    "args": ["-R", "0", "-mcp"],
    "env": {
      "ORACLE_HOME": "C:/Oracle/sqlcl/",
      "JAVA_TOOL_OPTIONS": "-Djdk.net.unixdomain.tmpdir=C:\\Temp -Djava.io.tmpdir=C:\\Temp",
      "JAVA_HOME": "C:\\Java\\jdk-21"
    }
  }
}

You have to change the SQLcl command to the absolute path of the binary.

Same for the JAVA_TOOL_OPTIONS; you need to specify where you've installed that specifically.

Regarding the arguments the -r -o tells SQLcl to not use restricted commands.

As to where to paste this in your file, see the below picture for a reference. Basically it goes at the top of the file.

You must restart Claude Desktop by quitting it from the taskbar because it likes to hide itself in the taskbar. Then restart the application.

Then go to File, Settings, Developer and then you will see your local MCP server running.

ENJOY!

What's the picture? Its Harrogate Cricket Club First Eleven in 1914. Photo hanging in Harrogate Cricket Club. Visit Yorkshire.