JDBC MCP Server

JDBC MCP Server

MCP server (stdio) that exposes read-only access to relational databases over JDBC: schema metadata, SELECT execution, execution plans, statistics and index analysis. Built-in dialects for PostgreSQL, Oracle, SQL Server, Firebird and SQLite (drivers bundled); other databases are served through DatabaseMetaData with an external driver.

Contents: Features · Typical Scenarios · Quickstart · Architecture · MCP Tools · MCP Resources · Read-only Protection · Server Environment Variables · Build · Stack · Troubleshooting · License

Features

• Engines: PostgreSQL 11+, Oracle 12c+, SQL Server 2012+, Firebird 3+, SQLite; generic JDBC via driverPath. Capabilities per engine: Supported Databases.
• Write protection: JSqlParser AST guard (single SELECT / WITH / EXPLAIN), plus session-, transaction- or file-level read-only mode where the engine supports it. Details: Read-only Protection.
• Connections: any number of databases in one connections.json; every tool takes a connection argument; pools are created on first use. Credentials are not read from the environment.
• Tools: 49, in 11 groups that can be disabled individually: metadata, query execution, plan analysis, column distribution and selectivity, table and index statistics, schema context, benchmarks, usage catalog. Reference: MCP Tools.
• Local catalog: per-connection SQLite file with a persistent structure snapshot and an index of known application queries (usage catalog).
• Clients: any MCP client with stdio transport; configuration examples for Claude Code, Codex CLI, OpenCode, VS Code, Copilot CLI, Cursor, Claude Desktop and Qwen Code in docs/clients.md.

Typical Scenarios

The agent picks the tools itself; these are the chains it usually follows. Every tool is described in MCP Tools.

Quickstart

1. Get the jar — download jdbc-mcp-server.jar from the latest release (JDK 21+ required; all JDBC drivers are bundled), or build it yourself:

./gradlew bootJar   # → build/libs/jdbc-mcp-server.jar

No local JDK? Use the Docker image ghcr.io/igorolv/jdbc-mcp-server instead — see Docker.

2. Describe your databases in ~/.jdbc-mcp-server/connections.json (%USERPROFILE%\.jdbc-mcp-server\connections.json on Windows, /data/connections.json in the Docker image) — one entry per database, keyed by the connection name:

{

"connections": { "orders": { "url": "jdbc:postgresql://db.example.com:5432/orders", "username": "ai_readonly", "password": "secret", "defaultSchema": "public", "description": "Order service — customers, orders, shipments", "structureSnapshotSchemas": ["public", "nsi"] }, "billing": { "url": "jdbc:oracle:thin:@//oracle.example.com:1521/BILLING", "username": "AI_READONLY", "password": "${BILLING_DB_PASSWORD}", "defaultSchema": "BILLING_OWNER", "description": "Legacy billing (Oracle)" }, "crm": { "url": "jdbc:sqlserver://sql.example.com:1433;databaseName=crm;encrypt=true", "username": "ai_readonly", "password": "secret", "defaultSchema": "dbo", "description": "CRM (SQL Server)" }, "legacy": { "url": "jdbc:firebirdsql://fb.example.com:3050//var/lib/firebird/data/app.fdb", "username": "SYSDBA", "password": "secret", "description": "Pre-2010 warehouse app (Firebird)" }, "archive": { "url": "jdbc:firebirdsql:embedded:/srv/data/archive-copy.fdb?nativeLibraryPath=/opt/firebird/lib", "username": "SYSDBA", "password": "secret", "description": "Copy of the warehouse archive, opened in-process (Firebird embedded)" }, "analytics": { "url": "jdbc:sqlite:/srv/data/analytics.db", "description": "Nightly analytics extract (SQLite)" }, "shop": { "url": "jdbc:mysql://mysql.example.com:3306/shop", "username": "ai_readonly", "password": "secret", "driverPath": "drivers/mysql-connector-j-9.1.0.jar", "description": "Web shop (MySQL, generic JDBC)" } } }

• url is the only required field; the engine is detected from its prefix. Any other URL needs a driverPath to a driver jar and is served as generic JDBC.
• description is returned by listConnections, so an agent picks a database by meaning; name the stand and any restriction ("PRODUCTION — keep queries small").
• archive opens a local Firebird file in-process: nativeLibraryPath is the directory holding libfbclient.so / fbclient.dll with its engine and plugins. Point it at a copy of the file — see Firebird.
• Use a read-only database user: it is the only protection that does not depend on this server. Keep the file readable only by its owner.

Every field, naming rules, ${VAR} secrets and several stands of one service: docs/connections.md.

3. Register the server with your MCP client — with no database settings in the client config:

{

"command": "java", "args": ["-jar", " /jdbc-mcp-server.jar"], "env": {} }

For Claude Code and Codex CLI that is one command:

claude mcp add --scope user jdbc -- java -jar /path/to/jdbc-mcp-server.jar

codex mcp add jdbc -- java -jar /path/to/jdbc-mcp-server.jar

OpenCode, VS Code with Copilot, Copilot CLI, Cursor, Claude Desktop, Qwen Code, and tips that apply to every client: docs/clients.md.

4. Try it. Ask the agent in plain words:

• *"Which databases can you reach?"* — it calls listConnections and lists the entries of your connections.json with their descriptions.
• *"How many tables are there in orders?"* — it calls listTables on that connection and counts them.

If the first call against a database fails, see Checking a configuration.

Architecture

 MCP client (Claude Code, Codex, VS Code, Cursor, ...)

| JSON-RPC over stdin / stdout, no network port v +- jdbc-mcp-server: one JVM, started by the client ------------------------------+ | | | MCP layer 49 tools in switchable groups, optional resources | | | every call names its connection | | v | | Connection registry <-- connections.json, read once at startup | | | a connection is built on its first call, then reused | | v | | Per-connection context | | +- read-only guard (JSqlParser AST) -> SQL executor (row cap, timeout) | | +- dialect: PostgreSQL, Oracle, SQL Server, Firebird, SQLite, generic | | +- metadata, statistics, plan parser and analyzer | | +- local catalog / / .db (SQLite, WAL): | | | structure snapshot + usage index of known queries | | +- Hikari pool of read-only JDBC connections -----------------> database | +--------------------------------------------------------------------------------+

• One process, many databases. The client starts the server as a child process and talks to it over stdio. The databases come from connections.json; a connection's pool, local catalog and services are created only when a tool call first names it, so a database that is down or misconfigured affects only the calls made against it.
• The SQL path. Every statement goes through the read-only guard first, then runs on a read-only JDBC connection with the connection's row cap and timeout. Engine-level protections are described in Read-only Protection.
• Dialects. Each engine has its own implementation of metadata queries, plans and statistics; any other database is served in generic mode through DatabaseMetaData and portable SQL — see Supported Databases.
• Local catalog. Structural metadata is persisted per connection in a SQLite file with no expiry: describeTable, the schema context tools and searchObjects read covered schemas from it and fall back to the live database otherwise. The same file holds the usage index. Live statistics, samples and plans are never cached. See Persistent Structure Snapshot and Usage Catalog.
• Execution model. Tool calls on one stdio session run sequentially. The MCP Java SDK 2.0.0 used by Spring AI 2.0.1 can lose responses when several concurrently executed tools finish at the same time, so the server keeps immediateExecution(true) until the SDK fixes this. A client's notifications/cancelled is not propagated to JDBC Statement.cancel(); the configured queryTimeoutSeconds (or a tool call's timeoutSeconds override) remains the server-side limit for a running SQL statement.

MCP Tools

The 49 tools are grouped below by purpose.

Every tool takes connection as its first, required argument, naming the database to run against — including installations that ser