Content
# Database MCP Server
Database MCP Server based on Java 21 and MCP Java SDK, currently supports:
- PostgreSQL
- Oracle
This repository has been split into a multi-module structure, allowing access to the local MCP client via `stdio` or providing a manageable server-side via `HTTP`.
## 1. Project Structure
- `database-mcp-core`
Shared core capabilities, including runtime assembly, database dialects, connection management, schema comparison, tool registration, etc.
- `database-mcp-stdio`
MCP Server based on standard input and output, suitable for local desktop clients or command-line host processes.
- `database-mcp-http`
HTTP version of MCP Server based on Spring Boot 3, including management backend, SQLite configuration storage, API Key verification, and other capabilities.
## 2. Main Capabilities
- Route to different database connections by `datasourceId`
- Support PostgreSQL / Oracle dialect differences
- Provide common database operation tools:
- Query
- DDL / DML execution
- Schema, table, index management
- Current user and database information query
- PostgreSQL table DDL export
- PostgreSQL schema comparison and synchronization SQL generation
- Support for HTTP mode:
- SQLite persistent configuration
- Web management backend
- API Key authentication
- Management password protection
## 3. Build
Requirements:
- JDK 21
- Maven 3.9+
Execute in the repository root directory:
```powershell
mvn clean package
```
Build only the HTTP module:
```powershell
mvn clean package -pl database-mcp-http -am
```
Build only the stdio module:
```powershell
mvn clean package -pl database-mcp-stdio -am
```
Common products:
- `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. Operation Mode
### 4.1 `stdio` Mode
`stdio` mode loads only one data source by default, and the configuration comes from environment variables.
Startup method:
```powershell
java -jar .\database-mcp-stdio\target\database-mcp-stdio-1.0.0.jar
```
Supported environment variables:
- `DB_TYPE`
Database type, supports `postgres` / `oracle`
- `DB_URL`
JDBC address
- `DB_USER`
Username
- `DB_PASSWORD`
Password
- `DB_SCHEMA`
Default schema
Compatible old variables:
- `PG_URL`
- `PG_USER`
- `PG_PASSWORD`
- `PG_SCHEMA`
Description:
- `DB_*` has higher priority than `PG_*`
- `stdio` mode maps this single configuration into the default data source, `datasourceId` is fixed and can be understood as `default`
- PostgreSQL uses `public` by default if no schema is explicitly configured
- Oracle does not enforce a default value if no schema is explicitly configured
### 4.2 HTTP Mode
Startup method:
```powershell
java -jar .\database-mcp-http\target\database-mcp-http-1.0.0.jar
```
Default service:
- HTTP port: `8080`
- MCP Endpoint: `/mcp`
- Management page: `http://localhost:8080/admin/index.html`
- Management API prefix: `/admin/api`
## 5. HTTP Configuration Model
In HTTP mode, instead of directly exposing the JDBC connection to the client, it uses `datasourceId` for secondary routing:
`datasourceId -> data source configuration -> basic JDBC configuration + schema`
The purpose of this is:
- The client only sends `datasourceId`
- The server-side uniformly maintains the real database connection information
- Multiple data sources can reuse the same set of basic JDBC address configurations
- Data sources can bind their own independent username, password, and default schema
### 5.1 SQLite Configuration Library
The HTTP service persists all basic configurations and data source mappings to SQLite.
Default file:
- `data/database-mcp-config.db`
Startup behavior:
1. The service first reads the SQLite configuration library.
2. The configuration library is initially created empty.
3. After the management backend is modified, it refreshes the data source routing in memory.
## 6. HTTP Configuration Example
Main configuration file:
- `database-mcp-http/src/main/resources/application.yml`
Example:
```yaml
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
```
Description:
- Oracle currently assembles connections by `SID`, does not support `serviceName`
- If `admin-password` is empty, the default management password is the server's current date, in the format `yyyy-MM-dd`
- If `api-key-enabled=false`, the MCP interface does not verify the API Key
## 7. Management Backend
Management backend page:
- `http://localhost:8080/admin/index.html`
Default request header:
- Management password header: `X-Admin-Password`
- API Key header: `X-API-Key`
Main purpose of the management backend:
- Maintain basic JDBC configurations
- Maintain data source configurations
- View and modify runtime routing data
Related backend files:
- `database-mcp-http/src/main/java/com/hbnrtech/mcp/http/admin/AdminConfigController.java`
- `database-mcp-http/src/main/java/com/hbnrtech/mcp/http/admin/RuntimeConfigurationService.java`
- `database-mcp-http/src/main/java/com/hbnrtech/mcp/http/admin/SqliteConfigRepository.java`
Related frontend files:
- `database-mcp-http/src/main/resources/static/admin/index.html`
- `database-mcp-http/src/main/resources/static/admin/admin.css`
- `database-mcp-http/src/main/resources/static/admin/admin.js`
## 8. API Key Mechanism
API Key format:
```text
clientId.timestamp.nonce.signature
```
Signature algorithm:
```text
Base64Url(HMAC_SHA256(secret, clientId.timestamp.nonce))
```
Verification rules:
- The signature must match
- The timestamp must be within the allowed window
- The API Key is not bound to a specific data source
Related implementation:
- `database-mcp-http/src/main/java/com/hbnrtech/mcp/http/config/ApiKeyAuthenticationFilter.java`
- `database-mcp-http/src/main/java/com/hbnrtech/mcp/http/config/ApiKeySignatureService.java`
## 9. MCP Tool Description
Core tool names start with `db_`, for example:
- `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`
The semantic boundaries of the three most commonly used tools are as follows:
- `db_list_tables`
Used for candidate table discovery and schema exploration, does not represent business data that has been queried, and should not be directly used for final business conclusions.
- `db_get_ddl`
Used for table structure, column, constraint, and other DDL verification, does not represent business data that has been queried, and should not be directly used for final business conclusions.
- `db_query`
Used to execute read-only SQL to obtain business data and evidence. For problems that require business conclusions, statistics, and trend analysis, the results of this tool should be used as the main basis.
A compatible alias is also provided:
- `pg_query`
- `pg_list_tables`
- `pg_describe_table`
- `pg_db_info`
These aliases are essentially the same set of implementations, but are provided for compatibility with old client naming.
### 9.1 Unified Parameter Rules
All tools automatically append the `datasourceId` parameter.
For example:
```json
{
"datasourceId": "order-db",
"tableName": "t_order"
}
```
Read operation example:
```json
{
"datasourceId": "order-db",
"sql": "select now()"
}
```
Description:
- The client must pass `datasourceId`
- `schema` can be omitted in most scenarios, and the server will determine it in the following order:
1. The `schema` explicitly passed in the request
2. The schema switched to by `db_switch_schema`
3. The default schema of the data source
4. PostgreSQL defaults to `public`
## 10. Database Capability Differences
Not all tools are completely equivalent for all databases.
In the current implementation:
- `db_get_ddl` is only implemented for PostgreSQL
- `db_compare_schemas` is only implemented for PostgreSQL
- Some index analysis capabilities depend on specific dialect support
- Oracle and PostgreSQL have differences in schema, identifier case sensitivity, and metadata query SQL
If a dialect does not support a certain capability, the tool will return a clear error message instead of silently degrading.
## 11. Key Source Code Locations
- `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. Test
Execute all tests:
```powershell
mvn test
```
## 13. License
MIT
