igorolv/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.
| Scenario | Example request | Tools |
|---|---|---|
| Answer a data question | "How many orders did each region ship last month?" | queryContext or schemaBrief → describeTable → findJoinPaths → validateQuery → executeQuery |
| Explore an unfamiliar schema | "What does the billing schema hold, and how are its tables related?" | schemaBrief → tableContext → sampleRows → schemaGraphDot |
| Check a query before running it | "Is this report query correct, and which tables does it really read?" | inspectQuery → queryLint → resolveQueryLineage → analyzePlan |
| Speed up a slow query | "Why is this query slow, and which index would help?" | analyzePlan → tableStats, indexStats → estimateSelectivity, columnDistribution, joinCardinality → benchmarkQuery |
| Audit indexes and schema | "Find missing and redundant indexes in the orders schema." | fkIndexCoverage, redundantIndexes, unusedIndexes, schemaLint |
| Learn from existing application SQL | "How does the application usually join customers and invoices?" | findQueriesByTable, findQueriesByColumn, observedRelationships |
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:
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:
- 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:
For Claude Code and Codex CLI that is one command:
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