Database MCP Server

基于 Java 21 和 MCP Java SDK 实现的数据库 MCP 服务，当前支持：

PostgreSQL
Oracle

这个仓库已经拆分为多模块结构，既可以通过 stdio 方式接入本地 MCP 客户端，也可以通过 HTTP 方式提供可管理的服务端。

1. 项目结构

database-mcp-core 共享核心能力，包括运行时装配、数据库方言、连接管理、Schema 对比、工具注册等。
database-mcp-stdio 基于标准输入输出的 MCP Server，适合本地桌面客户端或命令行宿主进程。
database-mcp-http 基于 Spring Boot 3 的 HTTP 版 MCP Server，包含管理后台、SQLite 配置存储、API Key 校验等能力。

2. 主要能力

按 datasourceId 路由到不同数据库连接
支持 PostgreSQL / Oracle 方言差异
提供常见数据库操作工具：
- 查询
- DDL / DML 执行
- Schema、表、索引管理
- 当前用户和数据库信息查询
- PostgreSQL 的表 DDL 导出
- PostgreSQL 的 Schema 对比与同步 SQL 生成
HTTP 模式下支持：
- SQLite 持久化配置
- Web 管理后台
- API Key 鉴权
- 管理口令保护

3. 构建

要求：

JDK 21
Maven 3.9+

在仓库根目录执行：

mvn clean package

只构建 HTTP 模块：

mvn clean package -pl database-mcp-http -am

只构建 stdio 模块：

mvn clean package -pl database-mcp-stdio -am

常见产物：

database-mcp-core\target\database-mcp-core-1.0.0.jar
database-mcp-stdio\target\database-mcp-stdio-1.0.0.jar
database-mcp-http\target\database-mcp-http-1.0.0.jar

4. 运行方式

4.1 `stdio` 模式

stdio 模式默认只加载一个数据源，配置来自环境变量。

启动方式：

java -jar .\database-mcp-stdio\target\database-mcp-stdio-1.0.0.jar

支持的环境变量：

DB_TYPE 数据库类型，支持 postgres / oracle
DB_URL JDBC 地址
DB_USER 用户名
DB_PASSWORD 密码
DB_SCHEMA 默认 Schema

兼容旧变量：

PG_URL
PG_USER
PG_PASSWORD
PG_SCHEMA

说明：

DB_* 优先级高于 PG_*
stdio 模式会把这个单一配置映射成默认数据源，datasourceId 固定可理解为 default
PostgreSQL 未显式配置 schema 时默认使用 public
Oracle 未显式配置 schema 时不强制默认值

4.2 HTTP 模式

启动方式：

java -jar .\database-mcp-http\target\database-mcp-http-1.0.0.jar

默认服务：

HTTP 端口：8080
MCP Endpoint：/mcp
管理页：http://localhost:8080/admin/index.html
管理 API 前缀：/admin/api

5. HTTP 配置模型

HTTP 模式不是直接把 JDBC 连接暴露给客户端，而是通过 datasourceId 做二级路由：

datasourceId -> 数据源配置 -> 基础 JDBC 配置 + schema

这样做的目的：

客户端只传 datasourceId
服务端统一维护真实数据库连接信息
多个数据源可以复用同一套基础 JDBC 地址配置
数据源可以绑定各自独立的用户名、密码、默认 Schema

5.1 SQLite 配置库

HTTP 服务会把所有基础配置和数据源映射持久化到 SQLite。

默认文件：

data/database-mcp-config.db

启动行为：

服务先读取 SQLite 配置库。
配置库首次创建为空。
管理后台修改完成后，会刷新内存中的数据源路由。

6. HTTP 配置示例

主配置文件：

database-mcp-http/src/main/resources/application.yml

示例：

server:
  port: 8080

database-mcp:
  http:
    endpoint: /mcp
    keep-alive-interval: 60s

    api-key-enabled: false
    api-key-header: X-API-Key
    api-key-secret: change-me-secret
    api-key-ttl-seconds: 300
    api-key-allowed-clock-skew-seconds: 30

    admin-api-base-path: /admin/api
    admin-password-header: X-Admin-Password
    admin-password: ""

    config-db-path: data/database-mcp-config.db

说明：

Oracle 当前按 SID 组装连接，不支持 serviceName
admin-password 留空时，默认管理口令为服务端当天日期，格式为 yyyy-MM-dd
api-key-enabled=false 时，MCP 接口不校验 API Key

7. 管理后台

管理后台页面：

http://localhost:8080/admin/index.html

默认请求头：

管理口令头：X-Admin-Password
API Key 头：X-API-Key

管理后台主要用途：

维护基础 JDBC 配置
维护数据源配置
查看和修改运行时路由数据

8. API Key 机制

API Key 格式：

clientId.timestamp.nonce.signature

签名算法：

Base64Url(HMAC_SHA256(secret, clientId.timestamp.nonce))

校验规则：

签名必须匹配
时间戳必须处于允许窗口内
API Key 不绑定具体数据源

9. MCP 工具说明

核心工具名以 db_ 开头，例如：

db_query
db_execute
db_list_schemas
db_list_tables
db_describe_table
db_create_table
db_alter_table
db_drop_table
db_get_ddl
db_list_indexes
db_create_index
db_drop_index
db_analyze_index
db_info
db_current_user
db_compare_schemas

其中三个最常用工具的语义边界如下：

db_list_tables 用于候选表发现和 schema 探索，不代表已经查到业务数据，也不应直接用于最终业务结论。
db_get_ddl 用于表结构、列、约束等 DDL 验证，不代表已经查到业务数据，也不应直接用于最终业务结论。
db_query 用于执行只读 SQL 以获取业务数据和证据。对需要业务结论、统计、趋势分析的问题，应以此工具的结果作为主要依据。

同时提供一套兼容别名：

pg_query
pg_list_tables
pg_describe_table
pg_db_info

这类别名本质上还是同一套实现，只是为了兼容旧客户端命名。

9.1 统一入参规则

所有工具都会自动追加 datasourceId 参数。

例如：

{
  "datasourceId": "order-db",
  "tableName": "t_order"
}

读操作示例：

{
  "datasourceId": "order-db",
  "sql": "select now()"
}

说明：

客户端必须传 datasourceId
schema 多数场景可省略，服务端会按以下顺序决定：
1. 请求显式传入的 schema
2. 当前会话通过 db_switch_schema 切换后的 schema
3. 数据源默认 schema
4. PostgreSQL 默认 public

10. 数据库能力差异

并不是所有工具对所有数据库都完全等价。

当前实现里：

db_get_ddl 仅对 PostgreSQL 实现
db_compare_schemas 仅对 PostgreSQL 实现
部分索引分析能力依赖具体方言支持
Oracle 和 PostgreSQL 在 schema、标识符大小写、元数据查询 SQL 上存在差异

如果某个方言暂不支持某项能力，工具会返回明确错误信息，而不是静默降级。

11. 关键源码位置

database-mcp-core/src/main/java/com/hbnrtech/mcp/bootstrap/DatabaseMcpRuntimeFactory.java
database-mcp-core/src/main/java/com/hbnrtech/mcp/execution/DatasourceRegistry.java
database-mcp-core/src/main/java/com/hbnrtech/mcp/execution/ConnectionManager.java
database-mcp-core/src/main/java/com/hbnrtech/mcp/tools/GenericMcpTools.java
database-mcp-http/src/main/java/com/hbnrtech/mcp/http/config/DatabaseMcpHttpProperties.java
database-mcp-http/src/main/java/com/hbnrtech/mcp/http/config/McpHttpServerConfiguration.java

12. 测试

执行全部测试：

mvn test

13. License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
database-mcp-core		database-mcp-core
database-mcp-http		database-mcp-http
database-mcp-stdio		database-mcp-stdio
docs		docs
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Database MCP Server

1. 项目结构

2. 主要能力

3. 构建

4. 运行方式

4.1 `stdio` 模式

4.2 HTTP 模式

5. HTTP 配置模型

5.1 SQLite 配置库

6. HTTP 配置示例

7. 管理后台

8. API Key 机制

9. MCP 工具说明

9.1 统一入参规则

10. 数据库能力差异

11. 关键源码位置

12. 测试

13. License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Database MCP Server

1. 项目结构

2. 主要能力

3. 构建

4. 运行方式

4.1 stdio 模式

4.2 HTTP 模式

5. HTTP 配置模型

5.1 SQLite 配置库

6. HTTP 配置示例

7. 管理后台

8. API Key 机制

9. MCP 工具说明

9.1 统一入参规则

10. 数据库能力差异

11. 关键源码位置

12. 测试

13. License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

4.1 `stdio` 模式