Db MCP Server

🚀 DB MCP Server

A Database MCP (Model Context Protocol) server based on Spring Boot and Spring AI, providing database access capabilities for AI applications.

🚀 Quick Start

Environmental Requirements

• Java 17 or higher
• Maven 3.6+
• One of the supported databases (MySQL, PostgreSQL, Oracle, SQL Server, KingBase)

Installation Steps

1. Clone the project

git clone https://github.com/KISS-GG/DB_MCP_Server.git
cd DB_MCP_Server

2. Build the project

mvn clean package

3. Run the service

# Method 1: Run with Docker
sh build.sh
docker-compose up -d

# Method 2: Run the JAR package
java -jar target/db-mcp-server-0.0.1.jar

4. Verify the service Access the health check endpoint:

curl http://localhost:8888/actuator/health

MCP Client Configuration

Configure in Claude Desktop or other MCP clients:

{
  "mcpServers": {
    "db-mcp-server": {
      "url": "http://localhost:8888/mcp",
      "transport": "streamable-http"
    }
  }
}

Monitoring Endpoints

Spring Actuator provides the following monitoring endpoints:

• http://localhost:8888/actuator/health - Health check
• http://localhost:8888/actuator/mappings - Endpoint mappings
• http://localhost:8888/actuator/beans - Bean information
• http://localhost:8888/actuator/env - Environment variables

✨ Features

• 🚀 Reactive architecture - High-performance asynchronous communication based on Spring WebFlux
• 🔌 Multi-database support - Supports MySQL, PostgreSQL, Oracle, SQL Server, and KingBase
• 🛡️ Safe and reliable - Built-in preview and confirmation mechanism for write operations to prevent accidental operations
• 📊 Metadata query - Supports querying database metadata such as table structure, indexes, and constraints
• 🔄 Transaction support - Batch SQL execution supports transactions to ensure data consistency
• 🎯 MCP protocol - Standardized AI tool call interface
• 📈 Monitoring ready - Integrated with Spring Actuator to provide health check and monitoring endpoints

Workflow

sequenceDiagram
    participant AI as AI Agent
    participant MCP as MCP Server
    participant DB as Database

    AI->>MCP: HTTP POST request (/mcp)
    MCP-->>AI: Return JSON response
    AI->>MCP: Send tool call request
    MCP->>DB: Execute database operation
    DB-->>MCP: Return result
    MCP-->>AI: Return execution result

Core Components

• MCP Server - Implemented based on Spring AI MCP Server Streamable HTTP
• HTTP endpoint - /mcp provides HTTP Streaming connection (POST method)
• Message endpoint - /mcp processes MCP protocol messages
• Tool provider - Automatically registers database operation tools through the @Tool annotation
• Connection pool - HikariCP high-performance database connection pool

💻 Usage Examples

Example 1: Query data in Claude Desktop

User question:

"Help me query all users in the users table of the test_db database whose age is greater than 25"

AI response: The AI will automatically call the executeQuery tool to execute the query and return the results.

Example 2: Safe write operation process

Step 1: Preview the write operation

User: "Update the status of the user with id 1 to 'active'"
AI: Call `executeWrite` and return preview information and `confirmId`

Step 2: Confirm the execution

User: "Confirm execution"
AI: Call `confirmWrite` and use the `confirmId` to execute the operation

Example 3: Query table structure

User question:

"View the structure of the users table"

AI response: The AI calls the getMetadata tool to return the complete structure information of the table, including column definitions, primary keys, and indexes.

Example 4: Batch operation

User question:

"Insert 3 user records in batch"

AI response: The AI calls the executeBatch tool to execute multiple INSERT statements in a transaction.

📚 Documentation

List of Available Tools

DB MCP Server provides the following 6 database operation tools:

1. executeQuery - Execute a query SQL

Execute a SELECT query statement and return the query results.

Parameters:

• dbType (required): Database type (mysql/postgresql/oracle/sqlserver/kingbase)
• host (required): Database host address
• port (required): Database port
• username (required): Username
• password (required): Password
• database (required): Database name
• sql (required): SQL query statement
• params (optional): SQL parameter list
• limit (optional): Result row limit, default is 1000
• timeout (optional): Timeout in seconds, default is 30
• useSsl (optional): Whether to use SSL

Example:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sql": "SELECT * FROM users WHERE age > ?",
  "params": [18],
  "limit": 100
}

2. executeWrite - Execute a write operation (preview mode)

Execute an INSERT/UPDATE/DELETE operation and return preview information and a confirmation ID.

Parameters:

• Basic connection parameters (same as executeQuery)
• sql (required): SQL write operation statement
• params (optional): SQL parameter list

Return:

• confirmId: Confirmation ID for subsequent confirmation execution
• preview: Operation preview information

Example:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sql": "UPDATE users SET status = ? WHERE id = ?",
  "params": ["active", 1]
}

3. confirmWrite - Confirm the execution of a write operation

Confirm and execute the previously previewed write operation.

Parameters:

• confirmId (required): Confirmation ID returned by executeWrite
• timeout (optional): Timeout in seconds, default is 30

Example:

{
  "confirmId": "abc123-def456-ghi789"
}

4. executeBatch - Execute SQL in batch

Execute multiple SQL statements in a single transaction. If any statement fails, all statements will be rolled back.

Parameters:

• Basic connection parameters (same as executeQuery)
• sqlList (required): List of SQL statements
• timeout (optional): Timeout in seconds, default is 30

Example:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sqlList": [
    "INSERT INTO users (name, age) VALUES ('Alice', 25)",
    "INSERT INTO users (name, age) VALUES ('Bob', 30)",
    "UPDATE users SET status = 'active' WHERE age > 20"
  ]
}

5. getMetadata - Query database metadata

Query database metadata such as table structure, indexes, constraints, and comments.

Parameters:

• Basic connection parameters (same as executeQuery)
• tableName (optional): Table name. If not provided, all table names will be returned.

Example:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "tableName": "users"
}

Return information:

• Table name and comments
• Column information (name, type, length, nullability, default value, comments)
• Primary key information
• Index information
• Foreign key constraints

6. executeDDL - Execute DDL statements

Execute DDL statements such as CREATE/ALTER/DROP (dangerous operations require confirmation).

Parameters:

• Basic connection parameters (same as executeQuery)
• sql (required): DDL statement
• confirmed (required): Confirm the execution of a dangerous operation (set to true for DROP/TRUNCATE/ALTER)
• timeout (optional): Timeout in seconds, default is 30

Example:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sql": "CREATE TABLE test (id INT PRIMARY KEY, name VARCHAR(100))",
  "confirmed": false
}

⚠️ Important Note

According to the global security constraints, deleting tables and data from the database is prohibited. Exercise extra caution when performing dangerous operations such as DROP/TRUNCATE/DELETE.

🗄️ Supported Databases

Database Connection Examples

MySQL:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "database": "mydb"
}

PostgreSQL:

{
  "dbType": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database": "mydb"
}

Oracle:

{
  "dbType": "oracle",
  "host": "localhost",
  "port": 1521,
  "database": "ORCL"
}

🔧 Technical Details

Core Frameworks

• Spring Boot 3.5.9 - Application framework
• Spring AI 1.1.2 - MCP Server support
• Spring WebFlux - Reactive Web framework

Database-related

• HikariCP - High-performance connection pool
• JDBC Drivers - Multi-database driver support

Tool Libraries

• Hutool 5.8.41 - Java utility library
• Lombok 1.18.42 - Simplify Java code

Monitoring and Operation

• Spring Boot Actuator - Application monitoring and management

Build Tools

• Maven 3.6+ - Project build management
• Java 17 - Runtime environment

Project Structure

db-mcp-server/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── top/zymnb/dbmcpserver/
│   │   │       ├── DbMcpServerApplication.java    # Application entry
│   │   │       ├── config/
│   │   │       │   └── McpConfig.java             # MCP configuration
│   │   │       └── service/
│   │   │           └── McpService.java            # MCP tool service
│   │   └── resources/
│   │       └── application.yml                     # Application configuration
├── pom.xml                                         # Maven configuration
└── README.md                                       # This file

❓ Frequently Asked Questions

Q1: How to configure the KingBase database driver?

The KingBase driver needs to be manually installed in the local Maven repository:

mvn install:install-file \
  -Dfile=kingbase8-8.6.0.jar \
  -DgroupId=cn.com.kingbase \
  -DartifactId=kingbase8 \
  -Dversion=8.6.0 \
  -Dpackaging=jar

Q2: What should I do if a timeout occurs when connecting to the database?

Check the following points:

1. Whether the database service is running normally
2. Whether the network connection is smooth
3. Whether the firewall allows the connection
4. Whether the database user permissions are correct
5. You can increase the timeout parameter value

Q3: How long is the validity period of the confirmId for write operations?

The default validity period of the confirmId is 5 minutes. After the timeout, you need to re-execute executeWrite to obtain a new confirmId.

Q4: Does it support connection pool configuration?

Yes. You can adjust the HikariCP connection pool parameters through environment variables or configuration files:

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 30000

Q5: How to handle large data queries?

1. Use the limit parameter to limit the number of returned rows
2. Perform paged queries on large datasets
3. Consider using indexes to optimize query performance
4. For extremely large result sets, it is recommended to export to a file

🤝 Contribution Guidelines

We welcome all forms of contributions!

How to Contribute

1. Fork the project
   • Click the Fork button in the upper right corner.
2. Create a feature branch

git checkout -b feature/your-feature-name

3. Commit your changes

git commit -m "Add: Your feature description"

4. Push to the branch

git push origin feature/your-feature-name

5. Create a Pull Request
   • Create a PR on GitHub.
   • Describe your changes in detail.

Code Style

• Follow the Java coding standards.
• Use Lombok to simplify the code.
• Add necessary comments and documentation.
• Ensure that all tests pass.

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2026 DB MCP Server Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Acknowledgments

Thanks to the following open-source projects and technologies:

• Spring Boot - A powerful Java application framework
• Spring AI - An AI application development framework
• MCP Protocol - Model Context Protocol
• HikariCP - High-performance connection pool
• Hutool - Java utility library

Special thanks to all contributors and users for their support!

⭐ Star History

If this project is helpful to you, please give us a star!