Oracle MCP (.NET)
A VS Code extension that gives AI agents (GitHub Copilot agent mode, Claude Code and other MCP clients)
read-only access to an Oracle database. The connection uses TCPS and logs in with a client certificate
from the Windows certificate store. No password is stored.
Features
- Tools:
query (one SELECT or WITH statement, read-only transaction) and whoami.
- Certificate login (external authentication) through ODP.NET Managed. Uses the same Oracle Net settings as
sqlplus.
- Certificate selection at startup: a Windows picker dialog, a remembered thumbprint, or a fixed thumbprint.
- Diagnostics:
--diagnose lists the certificates and tests each thumbprint in a separate process.
Requirements
- Windows 10 or 11 (certificate store and picker dialog).
- .NET 10 runtime (the server is framework-dependent).
- An Oracle 23ai (or compatible) database listening on TCPS.
- A client certificate in
CurrentUser\My with a private key, issued by a CA that the server trusts.
tnsnames.ora with the TCPS alias and a sqlnet.ora that points to the client wallet
(WALLET_LOCATION, for example METHOD = MCS).
Install
- Build the
.vsix (see Development) or download it from a release.
- In VS Code run Extensions: Install from VSIX... and select the file.
- Open Settings and search for
oracleMcp. Set at least oracleMcp.tnsAdmin.
- Start the server from the MCP list (
MCP: List Servers), then use it from agent mode.
Note: VS Code starts MCP servers only after the first chat message in the session.
Settings
| Setting |
Default |
Meaning |
oracleMcp.dsn |
freepdb_tls |
TNS alias from tnsnames.ora. |
oracleMcp.tnsAdmin |
(empty) |
Directory with tnsnames.ora and sqlnet.ora. |
oracleMcp.schema |
(empty) |
Schema set on connect. |
oracleMcp.maxRows |
200 |
Upper limit of rows per query. |
oracleMcp.certPicker |
true |
Show the certificate picker when no thumbprint is known. |
oracleMcp.certThumbprint |
(empty) |
Fixed thumbprint. Skips the picker. |
oracleMcp.certStoreFile |
(empty) |
File that remembers the thumbprint of the last successful login. |
Selection order: fixed thumbprint, then remembered thumbprint, then the picker. If the chosen certificate fails
and the picker is enabled, the picker is shown again.
Diagnostics
Run the server executable with --diagnose and a list of thumbprints:
$env:ORACLE_DIAG_THUMBPRINTS = 'THUMBPRINT1,THUMBPRINT2'
.\server\mcp-oracle-dotnet.exe --diagnose
The output shows the configuration (without secrets), the certificates with private keys, and a result for each
thumbprint. Each ORA error comes with a hint.
Security
- Only one
SELECT or WITH statement is accepted. Other statements are rejected before they reach the database,
and the transaction is set to READ ONLY.
- Schema names are validated before they are used in
ALTER SESSION.
- The private key never leaves the Windows certificate store.
- The extension stores no passwords. Keep the
certStoreFile and wallet directories out of source control.
Development
npm install
npm run build # compiles the extension and publishes the server to ./server
npm run package # creates the .vsix
The server is a .NET 10 console app (Program.cs, mcp-oracle-dotnet.csproj). The extension is in src/extension.ts.
License
MIT. See LICENSE.
