MCPDBWizard MCP server
Commit Nov 15, 2026Generates a custom Oracle MCP server that exposes specific PL/SQL packages, tables, and SQL statements as typed tools for AI agents.
Also known as srmadscience/mcpdbwizard-open, mcpdbwizard-open
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 2.0.47
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is MCPDBWizard MCP?
MCPDBWizard generates a custom Oracle MCP server that exposes specific PL/SQL packages, tables, and SQL statements as typed tools for AI agents.
Summary generated from the project's README
About MCPDBWizard MCP server
Developers working with enterprise Oracle databases can use MCPDBWizard to create highly specialized MCP servers that expose only selected database objects to AI agents. Instead of providing a generic SQL execution tool, this generator builds a custom Java-based server containing specific PL/SQL packages, tables, sequences, and tested SQL statements. This approach ensures that the AI agent interacts with the database through strictly typed tools rather than attempting to write raw SQL, which improves accuracy and prevents accidental data modifications.
The generation process uses a configuration file or an interactive Swing interface to select objects from the Oracle data dictionary. The resulting server supports Oracle versions 12c through 26ai and can run via stdio or Streamable HTTP. It handles complex Oracle types like records, collections, and REF CURSORs by converting them into JSON schemas, allowing the AI to understand exact parameter signatures. Users can implement optional security features like bearer-token authentication and TLS by configuring environment variables at runtime.
What you can do with it
- 1Exposing specific PL/SQL proceduresAn AI agent can call complex database logic using tools that carry a JSON Schema derived from the actual procedure signature.
- 2Securing database access for AIPrevent accidental data incidents by ensuring the AI only has access to specific, pre-defined tools rather than a general SQL runner.
- 3Managing complex Oracle data typesDevelopers can allow AI agents to interact with advanced types like records and cursors through standard JSON objects and arrays.
Written from the project's README. Every use case is checked against a quote from it.
How to install MCPDBWizard MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MCPDBWizard MCP in Claude Code
$ claude mcp add mcpdbwizard-open -- docker run -i --rm ghcr.io/srmadscience/mcpdbwizard:2.0.47Install MCPDBWizard MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcpdbwizard-open": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/srmadscience/mcpdbwizard:2.0.47"
]
}
}
}Install MCPDBWizard MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcpdbwizard-open": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/srmadscience/mcpdbwizard:2.0.47"
]
}
}
}Install MCPDBWizard MCP in VS Code CLI
$ code --add-mcp '{"name":"mcpdbwizard-open","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/srmadscience/mcpdbwizard:2.0.47"]}'Install MCPDBWizard MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcpdbwizard-open": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/srmadscience/mcpdbwizard:2.0.47"
]
}
}
}Install MCPDBWizard MCP in Codex
$ codex mcp add mcpdbwizard-open -- docker run -i --rm ghcr.io/srmadscience/mcpdbwizard:2.0.47Install MCPDBWizard MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcpdbwizard-open] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/srmadscience/mcpdbwizard:2.0.47"]
Install MCPDBWizard MCP in Gemini CLI
$ gemini mcp add -s user mcpdbwizard-open docker -- run -i --rm ghcr.io/srmadscience/mcpdbwizard:2.0.47Install MCPDBWizard MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcpdbwizard-open": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/srmadscience/mcpdbwizard:2.0.47"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesrmadscience/mcpdbwizard-open is public and reachablegithub.com/srmadscience/mcpdbwizard-open ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/srmadscience/mcpdbwizard-open ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCPDBWizard
An MCP server for Oracle, built from the objects you choose. Tick the PL/SQL packages, tables, sequences and your own tested SQL statements in a console, and it generates a Model Context Protocol server exposing exactly those to an AI agent as typed tools — each carrying a JSON Schema derived from the procedure's real signature.
There is no run-sql tool. Anything you did not select has no tool, no method and no
class: it is absent from the binary rather than refused at run time. Nothing composes a query
at run time either — the generated code is ordinary Java with fixed SQL statements and typed
binds, and the MCP server calls those wrappers rather than writing SQL for a model to run.
Generating that server means generating the whole calling layer, so you get it too: typed DAO factories, callable-statement wrappers, table managers and an optional SOAP layer. They are useful on their own, but the MCP server is the point.
Supports Oracle 12c through 26ai, and is regression-tested against six live instances spanning that range.
How the full product fits together. This repository is the generator — the config file, generate & compile, and the generated MCP server. The Design pages, Runtime page and proxy are the web console in the Docker image; here you select objects with the Swing tool or a config file instead, and the generated server can be run on its own.
The part that is hard
The usual way round is to hand the agent a run-sql tool, and it works until the
schema is real: published text‑to‑SQL accuracy falls sharply on enterprise‑scale schemas
compared with tidy benchmarks, and a wrong UPDATE is not a wrong answer, it is an incident.
The alternative is curated tools — but writing one per procedure by hand does not scale past a few, and PL/SQL is unusually hostile to deriving them automatically:
- a procedure can have any number of OUT and IN OUT parameters, not a single return value
- parameters can be records (including records nested inside records), collections,
%ROWTYPEs, REF CURSORs, package types, and overloads - Oracle's own data dictionary describes these differently between versions
This project does that derivation. Every generated MCP tool carries a real JSON Schema built from the procedure's actual signature, so the agent is told what the parameters are rather than inferring them from prose.
oracle: PROCEDURE order_summary(p_customer IN NUMBER,
p_totals OUT summary_rec,
p_lines OUT SYS_REFCURSOR)
tool: order_summary { "p_customer": <number> }
-> { "p_totals": { "orderCount": 12, "value": 4210.55 },
"p_lines": [ { "sku": "AB-1", "qty": 3 }, ... ] }
A record crosses as a JSON object, a REF CURSOR as an array of row objects, a DATE as an
ISO‑8601 string, RAW and binary vectors as base64, CLOB as text, BLOB as base64.
Quick start
Requires Java 21 and Maven. The Oracle JDBC driver (com.oracle.database.jdbc:ojdbc11)
comes from Maven Central — nothing to install by hand.
mvn clean package
That produces two jars in target/: a plain one, and a self‑contained
mcpdbwizard-app-<version>-shaded.jar with the driver bundled.
# Interactive (Swing) -- pick objects and options, save a config
java -jar target/mcpdbwizard-app-*-shaded.jar <log_dir> myconfig.pb2
# Batch -- regenerate from a saved config
java -jar target/mcpdbwizard-app-*-shaded.jar <log_dir> build myconfig.pb2
<log_dir> is created if missing.
Changed in 2026-08: there used to be a leading
<access_code>argument. It has been removed, and a command line that still passes one will be read as the log directory. It was validated for shape only — ≥19 characters, not a path, not the literalbuild— and then ignored, so it authenticated nothing. Drop it from any script that supplies it.
Configs are .pb2 (a flat properties file) or .json; both are accepted, and convert
losslessly either way:
java -cp target/mcpdbwizard-app-*-shaded.jar \
com.mcpdbwizard.schema.ConfigConverter myconfig.pb2 myconfig.json
What gets generated
| DAO factory | one entry point per config, wiring connections and logging |
| PL/SQL wrappers | a class per procedure/function — setParamX, executeProc, getParamY |
| Table managers | row CRUD by primary key, plus unique‑key, index and foreign‑key‑child lookups |
| SQL statement classes | your own SQL, with typed bind parameters |
| SOAP service layer | optional |
| JSON / JSON‑RPC connectors | optional |
| MCP server | optional (needs Java 17+ for the MCP SDK) |
Generated code depends only on com.mcpdbwizard.pub, the runtime library in this repository.
The MCP server
A single generated <Factory>McpServer.java, speaking stdio by default or Streamable
HTTP when started with http [port]. Optional bearer‑token auth and TLS both read their
secrets from the environment at run time and fail closed if unset, so no secret is baked into
the generated source.
It exposes PL/SQL routines, table row CRUD and secondary lookups, user SQL statements, sequences, and — on 23ai — JSON‑relational duality views with document CRUD and etag optimistic locking.
What is exposed is decided when you generate, not at run time. An object you did not select
has no code generated for it at all, and TABLE_MCP_CRUD_<i> narrows a table to any subset of
create/read/update/delete. An operation that is not exposed has no tool method emitted — it is
absent from the binary, not merely unregistered.
Oracle datatype support
Beyond the ordinary scalars and LOBs: 12c identity columns and extended VARCHAR2/RAW; 21c
native JSON; 23ai native BOOLEAN, VECTOR (dense, binary and sparse), and JSON‑relational
duality views.
Known gaps: TIMESTAMP WITH [LOCAL] TIME ZONE and BFILE cross as procedure parameters but not
yet as table columns; SDO_GEOMETRY has no JSON mapping, so a routine using one is skipped;
FLOAT16 vectors are blocked server‑side.
Logging
Generated factories pick a LogInterface implementation from the config: console, text file,
java.util.logging, Log4j 1.x, SLF4J, or Log4j 2. The SLF4J and Log4j 2 backends live
in com.mcpdbwizard.pub and depend only on the facade jar, which is an optional dependency —
supply the api plus a binding yourself if you use them.
Tests
The database‑free suite needs nothing and is green on a fresh clone:
mvn test
Tests that need Oracle are gated: with no database reachable they skip rather than fail. To point them at your own instance, copy the templates — the real files are gitignored and never leave your machine:
cp src/test/resources/test-boxes.properties.template src/test/resources/test-boxes.properties
cp Scripts/tns/tnsnames.ora.template Scripts/tns/tnsnames.ora
cp Scripts/boxes.env.template Scripts/boxes.env
Per setting, an environment variable (MCPDBWIZARD_TEST_HOST, …) always wins over the file, which
is how a run selects one server over another.
A third tier links against generator output: Scripts/testrun_current.sh regenerates code
from a set of configs and compiles it, and a family of harnesses then drives that code against a
live database.
That tier is not part of this repository, and neither are the schemas it needs. The configs introspect Oracle schemas whose structure is not ours to publish — some of it came from customer work years ago — and a config enumerates the schema it points at, so the configs cannot ship either. The harnesses go with them: they name those schemas' tables and routines, and they only compile against a regenerated tree that cannot exist here.
What that costs you: nothing to run the generator, and nothing to run the suite. The
database-free tests are complete and green on a fresh clone; the gated live tests skip. What you
do not get is a ready-made corpus to regenerate against. Scripts/check_provisioning.sh stays,
and will name the exact objects a config expects, which is the place to start if you build your
own.
examples/generated-output/ shows what the generator emits, with no database at all.
Repository layout
| Path | What |
|---|---|
src/main/java/com/mcpdbwizard/pub |
runtime library the generated code links against |
src/main/java/com/mcpdbwizard/app |
the generator — engine, Swing UI, shared helpers |
src/main/java/com/mcpdbwizard/schema |
typed model of a config; .pb2 ↔ .json |
src/main/java/com/mcpdbwizard/mcpdbwizardconnector |
JSON / JSON‑RPC connector generator |
examples/generated-output |
a checked‑in example of generator output, regenerated 2026‑08‑07 |
Scripts/ |
regeneration, provisioning checks, and the export gate |
| API docs | generated javadoc for com.mcpdbwizard.pub, the library you link against |
Contributor notes — architecture, conventions and accumulated gotchas — are in
CLAUDE.md.
API documentation
API docs for com.mcpdbwizard.pub
That is the runtime library generated code links against, and the only package documented — the generator's own internals are implementation, and publishing them would bury the part you call. The package summary explains what to reach for, and carries the compatibility contract: signatures there are load-bearing for every program this generator has produced, so they gain methods and do not change them.
The same pages are on the project site at mcpdbwizard.com/javadoc. Both are regenerated from source on publish rather than copied from one another.
Locally, mvn javadoc:javadoc writes them to target/reports/apidocs/. It runs with
failOnWarnings, so a broken @link fails the build rather than shipping a dead cross-reference.
Known issues
Known issues — what is wrong, what a caller
actually sees when it bites, and the workaround for each. Most of them do not announce themselves:
a record whose JSON keys are the generated field names rather than the column names, a VECTOR
routine parameter that takes a dense array only, a config whose tool count outgrows Oracle's
open_cursors.
Every open entry there is also an issue in this repository, linked from the page. Read it before filing — and if one of them is biting you, say so on its issue rather than opening a new one. Three of those entries are documented rather than fixed because nobody has asked, so a comment is the whole difference between "nobody has ever needed this" and "somebody does".
Contributing
See CONTRIBUTING.md. One thing to run before opening a pull request:
Scripts/export/check-export-clean.sh
It fails if a private hostname, a credential or a jar has crept into the tree.
Security
Please report a suspected vulnerability privately, not in a public issue — see
SECURITY.md.
Licence
Apache License 2.0 — see LICENSE and NOTICE.
Code this generator emits is your own work and carries no licence obligation from
this project. It links at run time against com.mcpdbwizard.pub, which is in this
repository and likewise Apache‑2.0, so you can ship generated applications under
whatever terms you like.
MCPDBWizard MCP questions
How do I add MCPDBWizard MCP to Claude Code?
Run claude mcp add mcpdbwizard-open -- docker run -i --rm ghcr.io/srmadscience/mcpdbwizard:2.0.47 in your terminal. Add --scope user to make it available in every project.
How do I add MCPDBWizard MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does this server allow running arbitrary SQL?
No, there is no run-sql tool. The server only exposes the specific objects you select during generation, and it uses fixed SQL statements with typed binds rather than composing queries at runtime.
How are complex Oracle types handled in the MCP tools?
Complex types are mapped to JSON: records become JSON objects, REF CURSORs become arrays of row objects, and binary vectors are converted to base64.
