JDBC MCP Server
A Model Context Protocol (MCP) server that provides read-only access to JDBC-compatible databases.
It also provides a framework that allows easy addition of other tools.
Key Ideas
- Safety
- Don't allow the database tools to make changes, AI makes mistakes, and sometimes you can't control permissions.
- Minimal external dependencies - Reduce the CVE surface
- Extensibility
- You should be able to add other tool/resource providers easily.
- Modern Java
- Latest LTS JVM
- Take advantage of its features
Quick Start
There are a couple of basic starter scripts that should run the mcp after a maven build. You can easily see what it does by running the client.
Build it
Requires Java 25 and a recent version of maven.
mvn package
Create Configuration File
See the Configuration section below for an example conifig file.
Run the Server
./run.sh
Run the GUI Client
./run-client.sh
Features
Server
- Multiple Databases - Connect to PostgreSQL, MySQL, Oracle, SQL Server, H2, SQLite
- The "Semantic Firewall" - JSqlParser validates that queries are in-fact queries, and therefore read-only, instead of relying on connection limits. Returning specific violations enables LLM self-correction for better success-per-prompt rates.
- Dynamic Drivers - JDBC drivers loaded on-demand from Maven Central
- Modular Architecture - Clean JPMS module structure utilizing SPI for extensible providers and zero compile-time dependencies.
- Minimal Dependencies - No Spring, minimal CVE surface
- jlink Ready - Build custom JVMs with only needed components
Client
The client should be able to run any mcp that uses the stdio transport. It's extremely helpful for debugging and building understanding of the mcp protocol.
- JavaFX GUI - Modern, responsive interface
- Tool Discovery - Automatically list server tools
- Dynamic Forms - Auto-generated input forms from schemas
- Pretty JSON - Formatted result display
- Any MCP Server - Works with any MCP-compatible server that uses the stdio transport
Modules
These are the JPMS modules currently included. If you wanted to add your own tools, you would create a module that is an mcp provider.
Available Tools
Available Resources
Resources provide navigable, HATEOAS-like access to database metadata. Start at db://context for a complete overview and follow the URIs to explore deeper.
Note: Clients that don't support the MCP resources protocol (e.g., some IDE Copilots) can access all resources via the resource-proxy tool.
Note:
schema/{name}already embedstables[]/views[]/procedures[]with navigation links, so a model that's already fetched a schema doesn't need the.../tablesor.../viewslist resources — they add onlyREMARKS/TABLE_TYPEbeyond what the schema resource already has.
"Human-in-the-Loop" Architecture & Testing
While this project accelerates development via AI assistance, its core value is the intentional, human-driven architecture.
- JPMS & SPI: The server uses JPMS ServiceLoader (SPI) to discover transport and provider modules at
runtime.
jmcp-serverhas no compile-time knowledge of specific tools or transports likejmcp-jdbcorjmcp-transport-stdio— they are runtime dependencies only. - Test Suite: There are hundreds of test cases that the Semantic Firewall logic against basic DML/DDL rejection, complex bypass attempts, and dialect-specific edge cases to give users confidence.
Configuration
The server reads a single JSON config file and routes each top-level section to the
corresponding provider by JPMS module name. Create file at its default location for a quick start: ~/.jmcp/config.json:
{
"org.peacetalk.jmcp.jdbc": {
"default_id": "mydb",
"connections": [
{
"id": "mydb",
"databaseType": "postgresql",
"jdbcUrl": "jdbc:postgresql://localhost:5432/mydb",
"username": "user",
"password": "pass",
"schemaFilter": ["public", "reporting"]
}
]
}
}
Connection fields
Config file search order
- System property:
-Djmcp.config=/path/to/config.json - Default location:
~/.jmcp/config.json
HTTP Proxy for Driver Downloads
JDBC drivers are downloaded from Maven Central on first use. If your environment requires an HTTP proxy, configure it using standard Java system properties or environment variables — no changes to the config file are needed.
Java system properties (pass on the command line or in run.sh):
-Dhttps.proxyHost=proxy.example.com
-Dhttps.proxyPort=8080
Downloads use HTTPS, so https.proxyHost/https.proxyPort are the standard
properties. http.proxyHost/http.proxyPort are also honored for
compatibility.
Environment variables (upper- or lower-case are both accepted; the value
must be http(s)://host[:port], port defaults to 80):
export HTTP_PROXY=http://proxy.example.com:8080
# or
export http_proxy=http://proxy.example.com:8080
Resolution order: https.proxyHost, then http.proxyHost, then HTTP_PROXY,
then HTTPS_PROXY. System properties always take precedence over environment
variables.
Proxies that require credentials (http://user:pass@host:port) are not
supported; such a value is ignored and a warning is logged.
Fail-fast initialization
If a provider's configure() throws — missing config, bad credentials, unreachable
database — the server prints the full stack trace and exits immediately. It will not
start in a degraded state. Providers must throw if they cannot be configured correctly.
Providers may also use their own configuration mechanisms (system properties, environment variables, etc.) in addition to the server-supplied config map.
Requirements
- Java 25+
- Maven 3.9+
- Network access to Maven Central: JDBC drivers are downloaded as needed
Security
The server enforces read-only access through:
- SQL Validation - JSqlParser validates queries before execution, they must be read-only.
- Read-Only Connections - HikariCP configured for read-only
Additionally, database users should have SELECT-only privileges.
Documentation
License
This project is licensed under the Apache License, Version 2.0.