jdbc-mcp-server
Read-only JDBC MCP server for exploring, querying, and analyzing relational databases through MCP tools and optional catalog resources.
Discover configured databases and get each connection name, description, engine, default schema, and catalog status (
listConnections).Explore metadata: schemas, tables, views, columns, keys, indexes, constraints, triggers, routines, sequences, views definitions, and object search.
Run read-only SQL:
SELECT,WITH, andEXPLAIN, with parameters, row limits, timeouts, truncation flags, and timed execution.Analyze SQL without running it: parse AST summaries, validate syntax/driver acceptance, lint queries, and trace lineage through views/routines.
Inspect execution plans: full textual plans or compact diagnostics for expensive nodes, full scans, estimate errors, nested loops, and sort spills.
Measure data shape and selectivity: column stats, top-N distributions, histograms, null ratios, predicate selectivity, and join cardinality estimates.
Audit object and index health: table/index sizes, row estimates, scan counters, unused indexes, redundant indexes, and foreign keys missing supporting indexes.
Benchmark queries: repeated cold/warm latency measurements or single timed runs with optional PostgreSQL
pg_stat_statementsdeltas.Explore schema relationships: table context, join paths, schema graphs, Graphviz DOT ERDs, schema briefs, and schema lint findings.
Work with a local usage catalog: index stored application/report SQL, find queries by table/column, inspect observed joins, browse business domains/tags/kinds, and retrieve full query records.
Rebuild the persistent local catalog for offline/faster metadata and usage lookups; catalog resources can expose manifests, tables, and columns when enabled.
Enforce read-only access via a JSqlParser guard, read-only JDBC connections, engine-level read-only modes where available, and recommended read-only database users.
Provides read-only access to PostgreSQL databases, allowing AI agents to run SQL queries, inspect execution plans, and explore database structure including tables, columns, indexes, foreign keys, views, functions, and sequences.
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 aconnectionargument; 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.
Related MCP server: mcp-multi-db
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?" |
|
Explore an unfamiliar schema | "What does the billing schema hold, and how are its tables related?" |
|
Check a query before running it | "Is this report query correct, and which tables does it really read?" |
|
Speed up a slow query | "Why is this query slow, and which index would help?" |
|
Audit indexes and schema | "Find missing and redundant indexes in the orders schema." |
|
Learn from existing application SQL | "How does the application usually join customers and invoices?" |
|
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.jarNo 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)"
}
}
}urlis the only required field; the engine is detected from its prefix. Any other URL needs adriverPathto a driver jar and is served as generic JDBC.descriptionis returned bylistConnections, so an agent picks a database by meaning; name the stand and any restriction ("PRODUCTION — keep queries small").archiveopens a local Firebird file in-process:nativeLibraryPathis the directory holdinglibfbclient.so/fbclient.dllwith 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", "<absolute-path>/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.jarOpenCode, 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
listConnectionsand lists the entries of yourconnections.jsonwith their descriptions."How many tables are there in
orders?" — it callslistTableson 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 <data-dir>/<name>/<name>.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
DatabaseMetaDataand 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 andsearchObjectsread 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'snotifications/cancelledis not propagated to JDBCStatement.cancel(); the configuredqueryTimeoutSeconds(or a tool call'stimeoutSecondsoverride) 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 serve exactly one database. listConnections lists the
names. See Several databases in one server.
Tool Groups
Tools are organised into groups that can be turned on or off independently with
JDBC_MCP_TOOLS_* flags. All groups are on by default, so the full tool set is available out of
the box. Turning groups off shrinks the tools/list manifest, which matters for small-context
(local) models that would otherwise be flooded with tool schemas before the first call.
Group | Flag | Default | Tools |
Metadata |
| on |
|
Query |
| on |
|
Admin |
| on |
|
Sample |
| on |
|
Query analysis |
| on |
|
Distribution |
| on |
|
Statistics |
| on |
|
Benchmark |
| on |
|
Usage catalog |
| on |
|
Schema context |
| on |
|
Connections |
| on |
|
Each flag accepts true / false. For a small-context local model, turn off the groups you do not
need — for example keep only Metadata + Query by setting the rest to false — to cut the manifest
down to a minimal "explore the schema and run a query" set. The sections below describe each tool
regardless of its group.
Query
Tool | Description |
| Execute a |
| Return the execution plan. PostgreSQL: |
| Compact LLM-oriented plan summary instead of a large raw plan dump: highest-cost nodes, full scans on large tables, estimate errors (planner vs. reality, requires |
| Validate syntax without execution: read-only guard plus driver |
| Parse SQL through JSqlParser without touching the database and return an AST summary: tables, aliases, CTEs, select items, joins, predicates, order by, columns, parameters, features, and parser warnings |
| Parse SQL and combine the AST with metadata, index, and FK checks. Returns advisory warnings such as unknown tables or columns, |
| Resolve direct objects referenced by a query and recursively expand database views/materialized views to underlying physical tables. Function/procedure expansion is best-effort: embedded |
Benchmarking
Tools for measuring the real cost of a query, so the LLM does not have to guess from the plan and can see actual milliseconds and buffer counters.
Tool | Description |
| Run the query |
| Regular |
Metadata
Tool | Description |
| List schemas. System schemas are hidden by default; use |
| List tables and views in a schema. Parameters: |
| Full object description in one call: columns, primary key, unique constraints, indexes, outgoing/incoming FKs, CHECK constraints and allowed values, plus compact trigger metadata |
| Trigger body for one named trigger. Parameters: |
| SQL definition of a view |
| Functions, procedures, and packages in a schema |
| Function or procedure source code. On Oracle, all |
| Sequences in one schema, or across schemas when |
| Case-insensitive substring search across non-system tables, views, routines, sequences, and synonyms |
Schema Context
High-level tools for quick schema orientation and SQL authoring. Instead of manually calling
listTables -> describeTable -> sampleRows for each table, an LLM can get ready-to-use
context in one call: tables, columns, relationships, constraints, and sample rows.
Tool | Description |
| Context around one table: the table itself, FK parents, and optionally child tables and relationship edges. FK traversal uses the requested depth (default 1, max 4). Parameters: |
| Find JOIN paths between two tables through FKs. The graph is traversed in both directions and each edge includes |
| Plain-text full-schema map for SQL authoring: all matching tables/views with column counts, PK, incoming/outgoing relationship counts, key-like columns, central/isolated tables, and capped key FK relationships. Use this first when relevant tables are unknown; follow with |
| Schema relationship graph metrics: nodes with in/out degree and classification, edges, central tables, isolated tables, connected components, and cycle hints. Optionally includes the shortest path between two tables |
| Schema lint audit: missing primary keys, FKs without indexes, FK type mismatches, nullable unique constraints, status/type columns without CHECK constraints, orphan |
| Build compact SQL-authoring context from search terms and/or explicit tables. Finds relevant tables and columns using declared schema names/comments plus usage-catalog semantic evidence when available, includes constraints and allowed values, relationships and JOIN paths between selected tables, and optionally sample rows (up to 3 per table) |
| DOT/Graphviz representation of the schema relationship graph. Nodes are tables with all columns and types ( |
Edge evidence
When includeObserved is left unset, tableContext / findJoinPaths enable
it automatically if the local usage catalog is enabled (see Usage Catalog below). Every
relationship edge then carries a typed three-layer evidence bundle. Each layer is independently
optional and is omitted when there is no signal:
declaredSchema— the relationship is a declared foreign key in the database catalog. Carries the FK name and column lists.observedQuery— the equi-join pair appears in stored application queries. CarriesjoinSupport(number of distinct queries) andqueryUids(up to 5 contributing uids).semanticUsage— terms shared across queries that touch both tables: business domains, business objects, and output labels, plus the co-occurring query count and uid preview. This layer decorates existing edges only — it never proposes new relationships.
{
"relationshipType": "foreignKey",
"fromTable": "ORDERS", "fromColumns": ["CUSTOMER_ID"],
"toTable": "CUSTOMERS", "toColumns": ["ID"],
"evidence": {
"declaredSchema": { "foreignKeyName": "FK_ORDERS_CUSTOMER", "fromColumns": ["CUSTOMER_ID"], "toColumns": ["ID"] },
"observedQuery": { "joinSupport": 18, "queryUids": ["SHOP/InvoiceReport.json#header"] },
"semanticUsage": {
"sharedBusinessDomains": [{ "value": "Customers", "support": 12, "queryUids": [...] }],
"sharedBusinessObjects": [{ "value": "Invoice payer", "support": 4, "queryUids": [...] }],
"sharedOutputLabels": [{ "value": "Payer name", "support": 3, "queryUids": [...] }],
"coOccurringQueryCount": 22,
"coOccurringQueryUids": [...]
}
}
}Equi-join pairs seen only in stored queries (no declared FK) are appended as new edges with
relationshipType: "observed" and undirected: true, between tables already in scope. Composite
(multi-column) FKs receive a declaredSchema layer but no observed-pair match in this iteration.
schemaBrief, schemaGraph, and queryContext only surface declared FK relationships.
Evidence model
The schema-context layer keeps three sources of knowledge separate:
declared_schema- live database introspection: tables, columns, PK/FK, indexes, constraints, comments and statistics.observed_query- the indexed query catalog: which stored application/report queries reference a table or column, and in which SQL context (select,where,join,order_by,having).semantic_usage- adapter-supplied business meaning: query domains/tags/labels, output labels, parameter descriptions, field usages, rendered business objects and confidence.
In tableContext, the existing table fields are the compact declared_schema view. When
includeObserved is enabled and the usage catalog is available, each table also gets an
evidence block:
{
"evidence": {
"observedQuery": {
"queryCount": 12,
"queryUids": ["SHOP/reports/customer-card#main"],
"columns": [
{"column": "STATUS", "queryCount": 5, "contexts": [{"value": "where", "support": 4}]}
]
},
"semanticUsage": {
"businessDomains": [{"value": "Customers", "support": 8}],
"businessTags": [{"value": "customer", "support": 6}],
"queryLabels": [{"value": "Customer card", "support": 3}],
"outputLabels": [{"value": "Customer name", "support": 4}],
"businessObjects": [{"value": "Customer card", "support": 3}]
}
}
}The server treats this as evidence, not as a single canonical business model. Different queries may legitimately attach different business roles to the same physical table or column.
queryContext also uses semantic_usage as a discovery signal. When the user passes natural
language terms, the server searches usage-catalog domains, tags, query labels, output labels and
business objects. Matching tables are returned in semanticMatches and are considered before the
fallback name/comment scan over live schema metadata. This lets terms such as "payer" find a
physical CUSTOMERS table when existing reports expose customers.name as "Payer name".
Usage Catalog
A catalog of known SQL usage against the inspected database, together with optional business context: parameters with descriptions, output columns with their meaning, and where each output is displayed in the consuming artifact (Excel cell in a BI Publisher report, dashboard widget, etc.).
There are two sources. File-backed usage comes from directories / JSON files / zip archives containing canonical QueryUsage JSON records. Database-native usage is derived automatically from the connected schema's views, routines and triggers. At runtime the server parses these records and builds a persistent SQLite index with extracted tables / columns / equi-join pairs as facts. JSON files remain authoritative for file-backed records; native records are refreshed from live metadata.
Purpose. The metadata tools answer "what tables and columns exist"; the usage catalog answers
"how are they used by applications". It supports lookups such as "which reports reference this
column" and "which business label does this output field carry", and it feeds the observedQuery
and semanticUsage layers of the relationship evidence bundle, so equi-joins seen in stored
queries appear next to declared foreign keys (for example, "these two columns are joined in 17
stored report queries", with their uids).
Identity. Each query is keyed by (source.kind, source.path, source.unit). Diagnostics and
evidence render this key as:
{source.kind}/{source.path}#{source.unit}The #unit suffix is omitted when there is no unit. Examples:
bi-publisher-report/reports/customers/CustomerCard.xdo#CUST
manual/manual/ad-hoc-2026-05-01
java-dao/src/main/java/com/example/shop/OrderDao.java#findByCustomersource.kind and source.unit must not contain / or #; source.path must not contain #.
For duplicate source keys, the first record wins for that index build.
Where the files live. The default catalog directory is
<data-dir>/<connection>/usage-catalog. Configure usageCatalogPaths on the connection as a list
of additional directories, .json files, or .zip archives. Directories are scanned recursively
for *.json; zip archives are scanned for JSON entries. Set usageCatalogEnabled: false to
disable the catalog. usageCatalogStatus then reports catalogEnabled: false; other public usage
tools return an argument error explaining how to enable it.
Database-native usage. The catalog also indexes supported database objects from the default schema:
views / materialized views as
source.kind="database-view"orsource.kind="database-materialized-view";functions and procedures as
source.kind="database-function"/source.kind="database-procedure"where the engine reports that distinction;triggers as
source.kind="database-trigger".
Views usually contribute fully parsed table, column and join evidence. Routine and trigger bodies
are engine-specific, so the indexer first uses an ANTLR-based procedural pre-extractor to find
embedded SELECT / WITH / INSERT / UPDATE / DELETE / MERGE statements, then feeds those
statements into the existing JSqlParser analysis pipeline. If no embedded statement is found, the
object is still kept as a provenance record. Use usageNativeSchemas on the connection to
scan explicit schemas.
Persistent index. The server never builds the usage index on startup. The first usage-catalog
lookup builds it synchronously from file-backed records and database-native objects into the local
SQLite <catalog>.db. Source files and database objects remain authoritative. Use
invalidateUsageCatalogCache after changing them; it clears the indexed usage rows and the next
lookup rebuilds them.
Local-only writes. The usage catalog never writes to the inspected JDBC database. The existing ReadOnlyGuard and connection-level protections
remain in force.
Typed payload. The canonical source, parameters[], outputs[], fieldUsages[] and nested
objects are described by the JSON Schema (field names, types, descriptions, enum values). The same
record types (QueryUsage and friends in usage/format/) are used by file indexing.
The canonical source-agnostic JSON format is documented in
docs/usage-catalog-format.md; its JSON Schema lives at
src/main/resources/schemas/query-usage-record.schema.json, with examples under
examples/usage/. Source-specific adapters should emit this canonical shape rather than being
implemented inside the JDBC MCP server.
Tool | Description |
| Current catalog state ( |
| Drop the runtime index. The next lookup rebuilds it synchronously from configured files and database-native objects |
| Full record selected by |
| Paginated listing with optional filters: |
| All catalog queries that reference a given table. Case-insensitive matching against alias-resolved, uppercased table names. Optional |
| All catalog queries that reference a given column, with the SQL |
| Aggregate observed equi-join pairs across stored queries, grouped by |
| Tags currently used in the catalog, with query counts. Lets the agent reuse a stable vocabulary across ingest calls |
| Same for |
| Source-kinds currently used in the catalog with their query counts. Helps the agent discover valid values for |
Resolution. During indexing, table / column qualifiers are resolved cheaply through the
parser's alias map and uppercased for case-insensitive matching. An explicit schema in the SQL
(SCHEMA.TABLE) is preserved verbatim. Unqualified table references are resolved as part of the
index build against the live JDBC schema: exactly one match fills the schema, multiple matches are
marked ambiguous, and zero matches stay unresolved.
Catalog Administration
Tool | Description |
| Rebuild the persistent structure snapshot and usage index for comma-separated |
This tool writes only to the local catalog. It does not modify the inspected database.
Connections
Tool | Description |
| List the databases this server serves: |
listConnections reads configuration and the local filesystem only — it opens no database
connection, so it still answers when some of the configured databases are down. In an unfamiliar
installation it is the first call worth making.
Persistent Structure Snapshot
Structural metadata (columns, keys, indexes, FKs, views, routines, triggers, sequences) is held in a
persistent structure snapshot stored in the local SQLite <catalog>.db file (the same database
file as the usage catalog, under <data-dir>/<catalog>/). SQLite runs in WAL mode, so Codex,
Claude, and other local agent processes can use the same catalog concurrently. This speeds up repeated calls to
tableContext, findJoinPaths, schemaLint, schemaGraph, queryContext, describeTable,
searchObjects, and the usage-catalog re-resolver. Statistics tools such as tableStats,
indexStats, columnStats, and sampleRows are not cached; their counters are live.
The snapshot is authoritative ("cache forever") — there is no TTL or staleness detection. It is
filled lazily (describeTable persists each table it loads) and can be front-loaded for whole
schemas with the rebuildCatalog tool, which builds the structure snapshot and the usage index
into one distributable <catalog>.db. rebuildCatalog checkpoints the WAL before returning.
Clear the catalog while all server processes are stopped by deleting <catalog>.db and any
adjacent <catalog>.db-wal / <catalog>.db-shm files.
Existing H2 <catalog>.mv.db files are not converted or deleted. On first SQLite startup the
server creates a new <catalog>.db, logs a warning, and leaves the legacy file untouched; run
rebuildCatalog to populate the new catalog.
Configuration:
structureSnapshotSchemas- schemas to front-load on a full rebuild (empty → the default schema).structureSnapshotOracleColumnQueryTimeoutSeconds- Oracle-only timeout for theDBMS_XMLGEN-backed bulk column/default query during a full rebuild (default300;0disables).
Both are per-connection fields in connections.json.
Data Exploration
Tool | Description |
| Return a few rows from a table or view ( |
Selectivity and Distribution
Tool | Description |
| Basic column statistics: |
columnStats only reports extremes. The other tools answer "how selective is this predicate?"
and "how skewed are values in this column?", which is the information an LLM needs to choose an
index or rewrite a JOIN meaningfully.
Tool | Description |
| Top-N most frequent values of a column plus their share. Surfaces skew, for example |
| Percentiles P25 / P50 / P75 / P90 / P95 / P99 plus |
| One scan for null / non-null counts across every table column. Columns are sorted by descending |
| Estimate how many rows a predicate would return without executing the query, using |
| Estimate the output row count of a |
Object Statistics
These tools give the LLM object scale and health signals; without that, optimization advice becomes
guesswork. Data comes from system catalogs (pg_class, pg_stat_*, ALL_TABLES, ALL_INDEXES,
DBA_SEGMENTS) and is aggregated on the Java side.
Tool | Description |
| Table and index sizes in bytes, estimated row count, dead tuples on PostgreSQL, last vacuum/analyze, and seq/idx scan counters. On Oracle, also includes best-effort |
| Per-index size, scan counter, columns, unique/primary flag, and index type. PostgreSQL extras: |
| Indexes with zero scans on PostgreSQL ( |
| Indexes whose column list is a strict prefix of another index on the same table. Unique indexes are not reported because dropping them would remove a constraint. Index type must match |
| Foreign keys on the child side that lack a supporting index, a classic cause of slow |
All tools are read-only; data is not modified.
MCP Resources
Besides tools, the server can publish the catalog as MCP resources, for clients that let the user
attach a table's description to the context. Resources are off by default; set
JDBC_MCP_RESOURCES_ENABLED=true to register them. The tools are the same either way.
Every usable connection publishes one resource and two resource templates:
URI | Name | Content |
|
| Database kind, the structure snapshot's version, build time and covered schemas, and the two templates below |
|
| What |
|
| One column with its primary-key position, unique constraints, indexes, outgoing and incoming foreign keys, and CHECK constraints |
<catalog>is the connection name, UTF-8 percent-encoded (ssj@devbecomesssj%40dev). It is fixed per connection, not a template argument: a read resolves its connection from the URI, so a URI never points at the wrong database — across the connections of one server or across several registered instances. Schema, table and column segments are percent-encoded and keep their case.Tables are not listed.
resources/listholds only the manifests; a schema with thousands of tables would otherwise turn it into a dump of the catalog. Clients discover names throughcompletion/completeon the template arguments —schema, thentable(givenschema), thencolumn(given both) — with case-insensitive prefix matches, at most 100 per response andhasMorewhen there are more.Completions come from the local catalog and never touch the database. Until a connection has a catalog they return nothing and the manifest reports snapshot version
0; a catalog built withrebuildCatalogis picked up without a restart. Table and column reads work either way: likedescribeTable, they answer from the snapshot and fall back to the live database.Metadata. Every read carries
_metawithcatalog,resourceSchemaVersion,snapshotVersionand, once a catalog exists,snapshotBuiltAt.Errors use MCP error codes: a table or column that does not exist is
-32002(resource not found,data.urinames the URI); a malformed URI is-32602(invalid params).
Read-only Protection
The server never writes to the inspected database, and does not rely on one mechanism for that:
a JSqlParser AST guard lets through a single
SELECT,WITHorEXPLAINand nothing else;every JDBC connection is read-only, and PostgreSQL, Firebird and SQLite enforce it inside the database (a read-only session or transaction, a file opened with
open_mode=1);database credentials are kept in
connections.json, never in the MCP client config or the environment, so an agent has no easy way around the server withpsqlorsqlplus.
The strongest guarantee is a read-only database user. The layers per engine, GRANT snippets for
PostgreSQL, Oracle and SQL Server, when the guard can be switched off, and why credentials live in a
file: docs/read-only.md. Tool errors, including the guard's rejected, are
listed in docs/errors.md.
Server Environment Variables
Databases, credentials and everything that varies per database live in
connections.json — deliberately
not in the environment. The
environment configures only the server process itself:
Variable | Required | Description |
| no | Path of the JSON file describing the named connections this server serves; default |
| no | Root directory for server-local data, default |
| no | Expose the catalog-qualified manifest and table/column resource templates with argument completion; default |
| no | Per-group tool toggles that control which tools appear in |
A connection's own settings — URL, credentials, default schema, timeouts, row caps, pool sizes, the
read-only guard, snapshot and usage options — are fields of its connections.json entry; see
Connection fields.
Build
# Set JDK 21+ explicitly if it is not your default JDK:
export JAVA_HOME="$HOME/.jdks/jdk-21.0.6"
./gradlew buildResult: build/libs/jdbc-mcp-server.jar (includes PostgreSQL, Oracle, SQL Server, Firebird, and SQLite drivers).
Stack
Java 21, Spring Boot 4.0, Spring AI MCP 2.0.1 (
stdiotransport)HikariCP through Spring Boot
starter-jdbcPostgreSQL JDBC 42.7.4
Oracle JDBC
ojdbc1123.6.0.24.10Microsoft SQL Server JDBC 12.8.1
Firebird JDBC (Jaybird) 6.0.6
SQLite 3.51.3 (
sqlite-jdbc): the WAL catalog (<catalog>.db) holding the usage index and persistent structure snapshot, and the driver for SQLite connectionsGradle 9.3.1 with version catalog
Troubleshooting
"Cannot find a Java installation ... matching languageVersion=21" - install JDK 21+ and set
JAVA_HOME. Gradle toolchains cannot download it without internet access.Connection refused / ORA-01017 / FATAL / SQL Server login failed - check the connection's
url,username, andpasswordinconnections.json. For PostgreSQL, test the URL withpsql; for Oracle, usesqlplus user/password@...; for SQL Server, test withsqlcmd -S host,1433 -d database -U user -P password.{"kind":"rejected","error":"Only SELECT / WITH / EXPLAIN statements are allowed"}- the guard worked. This is expected for any write operation. If the query is truly read-only, for example a read-only function call throughSELECT func(...), it will pass. For fully non-trivial cases, you can disable the guard with"readonlyGuard": "off"on that connection.Oracle write attempt reached the database - this should normally be blocked by the guard first. If
readonlyGuardisoff, rely on a read-only Oracle user; JDBCsetReadOnly(true)is only a best-effort hint for Oracle.Empty
describeTable/listTablesresult on Oracle - Oracle stores object names in uppercase. PassCUSTOMERS, notcustomers.Generic JDBC: "No driver in ... accepts the URL" - the jars in
driverPathregister no driver for that URL prefix. Check the URL, or name the class withdriverClass.Generic JDBC:
kind: "unsupported"- the tool needs something JDBC does not expose portably (plans, view sources, sequences). See Generic JDBC for what works.Firebird:
not_foundfromdescribeTable, orargumenterror "Firebird has no schemas" - Firebird stores unquoted names in uppercase and has no schemas: passCUSTOMERSand omitschema(or passPUBLIC).SQLite: "unable to open database file" - the path in the URL does not exist (the read-only open never creates a file) or is not readable. Use an absolute path; on Windows forward slashes work:
jdbc:sqlite:C:/data/app.db.Firebird: "unsupported on-disk structure" - the server version does not match the file's ODS (Firebird 3 reads ODS 12 only, Firebird 4/5 read ODS 13). Serve the file with the matching Firebird version, or back it up with
gbakand restore it on a newer one.SQL Server certificate errors - set the JDBC URL encryption options explicitly, for example
encrypt=true;trustServerCertificate=falsewith a trusted certificate, ortrustServerCertificate=trueonly for local/dev use.SQL Server
unusedIndexesunsupported - this tool intentionally avoidssys.dm_db_index_usage_statsbecause it usually requires elevated state-view permissions. UseindexStats,fkIndexCoverage, andredundantIndexesfor low-privilege SQL Server audits.The MCP client says the server failed to start - run
java -jar jdbc-mcp-server.jar < /dev/nullin a terminal; a malformedconnections.json, an invalid connection name or an unset${VAR}is reported there. See Checking the configuration.A setting in
connections.jsonhas no effect - unknown keys are ignored without a warning, so check the spelling against Connection fields. The file is read only at startup: restart or reconnect the server after editing it.A connection shows
configErrorinlistConnections- the entry is unusable (unsupported URL withoutdriverPath, unknowndialect, missing driver jar); the other connections keep working. Configuration errors lists every message.
License
This project is licensed under the Apache License, Version 2.0. See LICENSE.
Runtime and test dependencies are licensed by their respective owners. See
THIRD_PARTY_NOTICES.md, especially if you distribute a built fat jar containing bundled JDBC
drivers.
Available Tools
49 toolsanalyzePlananalyzePlanARead-onlyIdempotent
Diagnose query-plan performance with compact structured findings: expensive nodes, large-table full scans, estimation errors, risky nested loops and disk-sort spills. Use explainQuery when the full textual plan is required. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name.
Inputs: sql (required), connection (required), params, analyze, +1 more. Returns: LLM-friendly execution plan summary highlighting expensive nodes, full scans, e…
benchmarkQuerybenchmarkQueryARead-onlyIdempotent
Measure repeatable query latency with separate cold runs and min/median/max warm-run timings. Use for comparing query rewrites, not retrieving data; timedQuery is the one-run alternative that returns rows. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name. Returns the size of the last result (rows, columns, truncated), not the rows.
Inputs: sql (required), limit (required), connection (required), timeoutSeconds (required), +4 more. Returns: Wall-clock benchmark result for a read-only query, including cold and warm run…
columnDistributioncolumnDistributionARead-onlyIdempotent
Measure value frequency and skew for one known column by returning top-N values, counts and row shares. Use columnStats for only cardinality/extremes; runs GROUP BY + COUNT and may be expensive on large tables.
Inputs: table (required), column (required), connection (required), topN, +1 more. Returns: Top-N frequency distribution for a column, useful for detecting skew and low-se…
columnHistogramcolumnHistogramARead-onlyIdempotent
Measure percentile distribution for one orderable numeric, date, timestamp or text column: min/max, P25/P50/P75/P90/P95/P99 and null counts. Use columnDistribution for top frequent values instead.
Inputs: table (required), column (required), connection (required), schema. Returns: Percentile and null summary for an orderable column.
columnStatscolumnStatsARead-onlyIdempotent
Measure basic extremes and cardinality for one known column: total/non-null rows, distinct count and min/max. Use columnDistribution for frequent values or columnHistogram for percentiles.
Inputs: table (required), column (required), connection (required), schema. Returns: Basic one-column statistics: row counts, distinct count, and min/max values.
describeTabledescribeTableARead-onlyIdempotent
Inspect one known table or view. Use for its fields/columns, types, nullability, defaults, comments, keys, indexes, constraints or triggers. Returns full metadata for that object only; use tableContext when nearby relationships or joins are also needed.
Inputs: table (required), connection (required), schema. Returns: Full table or view description in one payload: columns, keys, indexes, constrai…
estimateSelectivityestimateSelectivityARead-onlyIdempotent
Estimate how selective one proposed table predicate is without executing the query. Returns planner-estimated rows, the unfiltered baseline and their ratio; use when evaluating filters or composite-index column order.
Inputs: table (required), predicate (required), connection (required), schema. Returns: Planner-only estimate of how selective a table predicate is.
executeQueryexecuteQueryARead-onlyIdempotent
Run a read-only SQL SELECT / WITH / EXPLAIN when actual result rows are needed. Use timedQuery for one timed execution or benchmarkQuery for repeated latency measurements. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name. Sets 'truncated' when the row cap is hit.
Inputs: sql (required), connection (required), limit, params, +2 more. Returns: QueryResult response payload.
explainQueryexplainQueryARead-onlyIdempotent
Return the full engine-specific textual execution plan for a SELECT / WITH statement. Use when raw plan detail is needed; prefer analyzePlan for compact performance findings. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name.
Inputs: sql (required), connection (required), params, analyze, +1 more.
findJoinPathsfindJoinPathsARead-onlyIdempotent
Find join paths when both endpoint tables are known but the intermediate relationships are not. Traverses declared FK and optional observed join edges in both directions; for one table's immediate neighborhood, use tableContext.
Inputs: toTable (required), fromTable (required), connection (required), maxDepth, +5 more. Returns: Foreign-key and observed-usage join paths between two tables, capped for concis…
findQueriesByColumnfindQueriesByColumnARead-onlyIdempotent
Find stored application/report queries that actually reference one column and show whether it appears in SELECT, WHERE, JOIN, ORDER BY or HAVING. Use describeTable to discover declared columns; schema/table filters are optional and case-insensitive.
Inputs: column (required), connection (required), table, schema. Returns: Usage-catalog matches for known SQL queries that reference a specific column.
findQueriesByTablefindQueriesByTableARead-onlyIdempotent
Find stored application/report queries that actually reference one known table. Use to learn observed filters, joins and business usage, not to inspect declared table structure; resolved names are matched case-insensitively.
Inputs: table (required), connection (required), schema. Returns: Usage-catalog matches for known SQL queries that reference a specific table.
fkIndexCoveragefkIndexCoverageARead-onlyIdempotent
Audit child-side foreign keys for missing supporting indexes. Returns only FKs not covered by an index starting with the FK columns in order, plus suggested index columns; use describeTable to inspect all keys and indexes of one table.
Inputs: connection (required), table, schema. Returns: Audit of child-side foreign keys that lack supporting indexes.
getQuerygetQueryARead-onlyIdempotent
Retrieve the complete stored record for one query whose source identity is already known. Returns SQL, parameters, parsed tables/columns/joins, outputs and field usages; use listQueries, findQueriesByTable or findQueriesByColumn to discover matching records first.
Inputs: connection (required), sourceKind (required), sourcePath (required), sourceUnit. Returns: Full usage-catalog record for one known query, including SQL text, parsed refer…
getRoutineDefinitiongetRoutineDefinitionARead-onlyIdempotent
Return the source code of one known function, procedure or package, including its body where available. Use listRoutines to discover routine names.
Inputs: name (required), connection (required), schema.
getTriggerDefinitiongetTriggerDefinitionARead-onlyIdempotent
Return the full definition/body of one known table trigger. For trigger names and compact metadata, use describeTable first.
Inputs: table (required), trigger (required), connection (required), schema.
getViewDefinitiongetViewDefinitionARead-onlyIdempotent
Return the SQL text that defines one known view or materialized view. For its exposed fields, keys and other object metadata, use describeTable.
Inputs: name (required), connection (required), schema.
indexStatsindexStatsARead-onlyIdempotent
Inspect index definitions together with operational size, usage and cardinality counters for one table or a schema. Use describeTable for structural metadata of one table without live index statistics.
Inputs: connection (required), table, schema. Returns: Index statistics for a schema or table, including size, columns, uniqueness, an…
inspectQueryinspectQueryARead-onlyIdempotent
Inspect SQL syntax and structure without accessing a database. Returns a parser-derived AST summary of tables, aliases, expressions, joins, predicates, ordering, columns and parameters; use validateQuery for driver validation or queryLint for metadata-aware advice.
Inputs: sql (required), connection (required). Returns: Parsed SQL authoring summary: statement type, tables, aliases, CTEs, joins, pre…
invalidateUsageCatalogCacheinvalidateUsageCatalogCacheARead-onlyIdempotent
Force the server-local usage index to be rebuilt after its configured sources change. Invalidates only the runtime/local index; the next usage lookup rebuilds it synchronously and no inspected database data is modified.
Inputs: connection (required). Returns: Runtime status of the usage catalog index and configured sources.
joinCardinalityjoinCardinalityARead-onlyIdempotent
Estimate the output size and selectivity of a proposed equi-join between two known tables without executing it. Returns planner estimates for both sides and versus the Cartesian product; use findJoinPaths when the join route itself is unknown.
Inputs: toTable (required), fromTable (required), connection (required), leftColumn (required), +4 more. Returns: Planner estimate for joining two tables on a pair of columns without executing…
listConnectionslistConnectionsARead-onlyIdempotent
Discover the databases served here and the valid name to pass as 'connection'. Call when the target connection is not already established; returns purpose, engine, default schema and local-catalog availability without opening a database connection.
Inputs: no named parameters. Returns: Databases configured on this server; every other tool names one of them.
listKnownDomainslistKnownDomainsARead-onlyIdempotent
Discover the existing business-domain vocabulary and query counts for reuse in listQueries filters.
Inputs: connection (required). Returns: Known business domains discovered in the usage catalog.
listKnownKindslistKnownKindsARead-onlyIdempotent
Discover valid usage-catalog source-kind values and their query counts for reuse in listQueries filters.
Inputs: connection (required). Returns: Known source-kind values discovered in the usage catalog.
listKnownTagslistKnownTagsARead-onlyIdempotent
Discover the existing business-tag vocabulary and query counts for reuse in listQueries filters.
Inputs: connection (required). Returns: Known business tags discovered in the usage catalog.
listQuerieslistQueriesARead-onlyIdempotent
Browse or search stored usage-catalog queries by source, business metadata, parse status or free text. Returns summaries newest-ingest first; use getQuery for the complete SQL and evidence of one selected record.
Inputs: connection (required), tag, limit, offset, +5 more. Returns: Paged list of usage-catalog query records matching the supplied filters.
listRoutineslistRoutinesARead-onlyIdempotent
Discover function, procedure and package names in a schema, optionally by name pattern. Use getRoutineDefinition when the source of one known routine is needed.
Inputs: connection (required), schema, namePattern. Returns: List of routines returned by listRoutines.
listSchemaslistSchemasARead-onlyIdempotent
Discover schema names visible to the current user when the target schema is unknown. Use listTables next to enumerate objects in one schema.
Inputs: connection (required), includeSystem. Returns: List of schema names returned by listSchemas.
listSequenceslistSequencesARead-onlyIdempotent
Discover sequence names and metadata in one schema, or across all schemas when schema is omitted.
Inputs: connection (required), schema. Returns: List of sequences returned by listSequences.
listTableslistTablesARead-onlyIdempotent
Enumerate table and view names in a known schema, optionally filtered by name or type. Does not return fields/columns; use describeTable for one object's structure.
Inputs: connection (required), types, schema, namePattern. Returns: List of tables and views returned by listTables.
nullRationullRatioARead-onlyIdempotent
Find sparse or mostly-null fields across every column of one table in a single scan. Returns null/non-null counts and ratios sorted by sparsity; use describeTable when only declared nullability is needed.
Inputs: table (required), connection (required), schema. Returns: Per-column null ratio report for a table.
observedRelationshipsobservedRelationshipsARead-onlyIdempotent
Discover empirically observed equi-join column pairs from stored queries, with support counts and contributing query IDs. Use findJoinPaths for declared/combined paths between endpoints; non-equi joins are excluded.
Inputs: connection (required), table, schema, minSupport. Returns: Observed join relationships aggregated from known SQL queries.
queryContextqueryContextARead-onlyIdempotent
Build multi-table SQL-authoring context from natural-language terms or an explicit table list. Use when relevant tables are unknown or a request spans several tables; for one known table's fields or structure, use describeTable.
Inputs: connection (required), terms, schema, tables, +2 more. Returns: Authoring context selected from schema terms or requested tables, with relevant…
queryLintqueryLintARead-onlyIdempotent
Review authored SQL for advisory metadata and indexing problems without executing it. Reports unknown objects, SELECT *, conditionless joins, unindexed FKs and non-leading predicate/order columns; use validateQuery when database-driver acceptance is the question.
Inputs: sql (required), connection (required), schema. Returns: Query lint result that combines SQL inspection with metadata checks.
rebuildCatalogrebuildCatalogARead-onlyIdempotent
Create or refresh the persistent local catalog for offline/repeated metadata and usage lookups. Captures configured schema metadata, rebuilds the usage index and returns the distributable catalog file; writes only server-local data, never the inspected database.
Inputs: connection (required), schemas. Returns: Outcome of a full catalog rebuild: the persistent structure snapshot plus the u…
redundantIndexesredundantIndexesARead-onlyIdempotent
Find structurally overlapping non-unique indexes whose leading columns are a strict prefix of another same-type index. Unlike unusedIndexes, this does not depend on workload scan counters.
Inputs: connection (required), table, schema. Returns: Indexes that appear redundant because their leading columns are covered by anot…
resolveQueryLineageresolveQueryLineageARead-onlyIdempotent
Trace a query's data lineage from direct FROM/JOIN objects through views and optionally routines to underlying physical tables. Use inspectQuery for direct AST references only; routine expansion is best-effort and may miss dynamic SQL.
Inputs: sql (required), connection (required), schema, maxDepth, +2 more. Returns: Lineage analysis of a query, including direct references, expanded physical tab…
sampleRowssampleRowsARead-onlyIdempotent
Preview a small number of actual rows from one known table or view to understand data shape and example values. For fields, types and constraints without reading row data, use describeTable.
Inputs: table (required), connection (required), limit, schema. Returns: QueryResult response payload.
schemaBriefschemaBriefARead-onlyIdempotent
Discover candidate tables and views across a schema when their names are unknown. Returns a broad plain-text map with column counts, PKs and relationship summaries; follow with queryContext for multi-table authoring detail or describeTable for one known object.
Inputs: connection (required), terms, schema, maxTables.
schemaGraphschemaGraphARead-onlyIdempotent
Analyze schema-wide relationship topology: graph nodes/edges, central or isolated tables, components, cycle hints and an optional shortest path. Use findJoinPaths when only paths between two known tables are needed.
Inputs: connection (required), schema, toTable, maxDepth, +2 more. Returns: Schema relationship graph metrics and edges for understanding table connectivit…
schemaGraphDotschemaGraphDotARead-onlyIdempotent
Export a schema or selected tables as DOT/Graphviz ERD text with columns, types, PK/FK markers and join edges. Use schemaGraph for graph metrics rather than renderable diagram source.
Inputs: connection (required), schema, tables.
schemaLintschemaLintARead-onlyIdempotent
Audit one table or a schema for modeling and indexing risks: missing PKs, unindexed or mismatched FKs, nullable unique columns, missing CHECKs/remarks, orphan *_id columns, isolation and wide tables. Returns findings, not general table metadata.
Inputs: connection (required), table, checks, schema, +2 more. Returns: Schema lint audit result with capped findings for modeling, indexing, and data-…
searchObjectssearchObjectsARead-onlyIdempotent
Find database objects when only a full or partial name is known. Searches non-system tables, views, routines, packages, sequences and synonyms case-insensitively; use describeTable after finding a table or view whose structure is needed.
Inputs: connection (required), namePattern (required). Returns: Cross-object search results returned by searchObjects.
tableContexttableContextARead-onlyIdempotent
Explore the relationship neighborhood of one known table: compact root/nearby table metadata plus declared FK and optional observed join edges. Use when nearby joins are needed; for only the table's own fields or structure, use describeTable.
Inputs: table (required), connection (required), depth, schema, +3 more. Returns: Neighborhood around a root table, including related tables and relationship edg…
tableStatstableStatsARead-onlyIdempotent
Inspect operational size and activity statistics for one known table: estimated/live rows, storage, dead tuples, maintenance times and scan counters. For fields, keys and constraints, use describeTable; available statistics depend on engine and privileges.
Inputs: table (required), connection (required), schema. Returns: Engine-specific table size, row estimate, activity, maintenance, and storage st…
timedQuerytimedQueryARead-onlyIdempotent
Measure one read-only SQL SELECT / WITH / EXPLAIN while still returning its rows and elapsed time. Use executeQuery when timing is irrelevant or benchmarkQuery for repeated cold/warm measurements. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name. Adds available per-statement counter deltas (calls, execution time, rows, buffer hits/reads).
Inputs: sql (required), connection (required), limit, params, +2 more. Returns: Query execution result with wall-clock elapsed time and optional pg_stat_statem…
unusedIndexesunusedIndexesARead-onlyIdempotent
Find non-PK/non-unique indexes with zero recorded scans as removal candidates. Unlike redundantIndexes, this uses workload counters, which are meaningful only after representative traffic and are not supported by every engine.
Inputs: connection (required), schema, minSizeBytes. Returns: PostgreSQL unused-index audit result; other engines may return a support note i…
usageCatalogStatususageCatalogStatusARead-onlyIdempotent
Check whether the usage catalog is enabled and ready before relying on observed-query or semantic evidence. Returns configured sources, indexing state, counts and load errors without searching for queries.
Inputs: connection (required). Returns: Runtime status of the usage catalog index and configured sources.
validateQueryvalidateQueryARead-onlyIdempotent
Check whether the database driver accepts a SELECT / WITH / EXPLAIN without executing it: prepares the statement and validates parameters, syntax and referenced objects. Use inspectQuery for parser-only AST inspection or queryLint for advisory metadata/index warnings. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name.
Inputs: sql (required), connection (required), params, namedParams. Returns: Validation result for a SQL statement, including guard, parameter, driver, and…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
Many tools have clearly distinct purposes, and descriptions cross-reference alternatives (e.g., explainQuery vs analyzePlan). However, dense clusters around query analysis (executeQuery/timedQuery/benchmarkQuery/validateQuery/queryLint), column profiling (columnStats/columnDistribution/columnHistogram/nullRatio), and index auditing (fkIndexCoverage/redundantIndexes/unusedIndexes/indexStats) create real overlap that can cause misselection.
All names are camelCase and readable, but the convention mixes verb-first actions (listTables, describeTable, findJoinPaths) with noun-only analysis results (columnStats, schemaGraph, indexStats). This is not a consistent verb_noun pattern, though it remains understandable.
49 tools is far above the 3–15 ideal and exceeds the 25-tool threshold for being too many. The domain is broad, but several overlapping clusters could likely be consolidated into fewer multi-purpose tools.
The read-only introspection surface is extremely thorough: connections, schemas, tables/views, routines, triggers, sequences, columns, stats, indexes, joins, query parsing/validation/execution/plans/lineage, and usage-catalog discovery. Minor gaps exist (e.g., no standalone listTriggers or listViews, relying on listTables/searchObjects), but agents can work around them.
Maintenance
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted PostgreSQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceRead-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.MIT
- AlicenseAqualityBmaintenanceRead-only MCP server for querying PostgreSQL, MySQL, and SQLite from AI agents — multi-database, safe by default.4268 npm1ISC
- FlicenseNot gradedqualityDmaintenanceA read-only MCP server that enables AI agents to explore database schemas and execute safe queries on PostgreSQL and MySQL.-
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server that lets coding AI agents inspect Oracle Database schema through live metadata.ISC