# Mcp Db Server

> 🔥 让 AI 直接操刀你的数据库！无状态 MCP 数据库服务，支持 MySQL / PostgreSQL / SQLite / SQL Server / Oracle / H2，连接参数即传即用，零持久化零配置。

- **Type:** MCP server
- **Install:** `agentstack add mcp-perfectxm-mcp-db-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PerfectXM](https://agentstack.voostack.com/s/perfectxm)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PerfectXM](https://github.com/PerfectXM)
- **Source:** https://github.com/PerfectXM/mcp-db-server

## Install

```sh
agentstack add mcp-perfectxm-mcp-db-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-db-server

[](LICENSE)
[](https://adoptium.net/)
[](https://spring.io/projects/spring-boot)
[](https://modelcontextprotocol.io/)

基于 **Spring AI MCP Server** 的通用数据库 MCP 服务。**完全无状态**——数据库连接信息由 AI 客户端在每次调用时传入，服务端不存储任何连接配置或数据。

支持 **MySQL、PostgreSQL、H2、SQLite、SQL Server、Oracle** 六大数据库。

---

## 目录

- [特性](#特性)
- [设计理念](#设计理念)
- [支持的数据库](#支持的数据库)
- [快速开始](#快速开始)
  - [Maven 本地运行](#maven-本地运行)
  - [Docker 部署](#docker-部署)
  - [JAR 包部署](#jar-包部署)
- [MCP 工具接口](#mcp-工具接口)
- [集成到 AI 客户端](#集成到-ai-客户端)
- [项目结构](#项目结构)
- [开发指南](#开发指南)
- [License](#license)

---

## 特性

- 🔌 **MCP 协议**：基于 Spring AI MCP Server，SSE 传输协议，无缝对接 Claude Desktop、Cursor 等 AI 客户端
- 🗄️ **多数据库支持**：MySQL、PostgreSQL、H2、SQLite、SQL Server、Oracle
- 🔓 **完全无状态**：不存储任何连接配置或数据，连接信息由客户端在每次调用时传入
- 🚀 **HikariCP 连接池**：相同连接参数自动复用短期缓存（5分钟 TTL），兼顾性能与安全
- 🐳 **Docker 部署**：提供 Dockerfile 和 docker-compose.yml
- 🛠️ **6 个 MCP 工具**：表查询、表结构、索引、SQL 查询、SQL 写操作、数据库元信息

---

## 设计理念

```
┌──────────────┐    连接参数(每调)    ┌──────────────────┐     JDBC     ┌────────────┐
│  AI 客户端    │ ──────────────────▶ │  mcp-db-server   │ ───────────▶ │  数据库     │
│ (Claude等)   │ ◀────────────────── │  (无状态服务)      │ ◀─────────── │ (MySQL等)  │
└──────────────┘    查询结果           └──────────────────┘              └────────────┘
```

- 服务端**不持久化**任何数据库连接信息
- AI 客户端每次调用工具时，将 `type`、`host`、`port`、`database`、`username`、`password` 作为参数传入
- 服务端在内存中短期缓存连接池（5 分钟 TTL），相同参数自动复用，过期自动释放
- 权限由数据库用户自身的 GRANT 决定，服务端不做额外拦截

---

## 支持的数据库

| 数据库       | 类型标识     | 默认端口 | 状态   |
| ------------ | ------------ | -------- | ------ |
| MySQL        | `mysql`      | 3306     | ✅ 稳定 |
| PostgreSQL   | `postgresql` | 5432     | ✅ 稳定 |
| H2           | `h2`         | -        | ✅ 稳定 |
| SQLite       | `sqlite`     | -        | ✅ 稳定 |
| SQL Server   | `sqlserver`  | 1433     | ✅ 稳定 |
| Oracle       | `oracle`     | 1521     | ✅ 稳定 |

---

## 快速开始

### 环境要求

- **JDK** 17+ （推荐 JDK 21）
- **Maven** 3.6+ （或使用项目内置的 Maven Wrapper）
- **Docker** （可选）

### Maven 本地运行

```bash
# Windows (PowerShell)
.\mvnw.cmd spring-boot:run

# Linux / macOS
./mvnw spring-boot:run
```

服务启动后，MCP SSE 端点为 `http://localhost:8088/sse`。

### Docker 部署

```bash
# 构建镜像
docker build -t mcp-db-server .

# 运行容器
docker run -d -p 8088:8088 --name mcp-db-server mcp-db-server
```

### JAR 包部署

```bash
./mvnw clean package -DskipTests
java -jar target/mcp-db-server-1.0.0.jar
```

---

## MCP 工具接口

每个工具都需要 AI 客户端传入完整的数据库连接参数。

### 公共连接参数（每个工具方法都包含）

| 参数       | 类型   | 必填 | 说明                              |
| ---------- | ------ | ---- | --------------------------------- |
| `type`     | String | ✅   | 数据库类型：mysql, postgresql, h2, sqlite, sqlserver, oracle |
| `host`     | String | ✅   | 数据库主机地址                    |
| `port`     | int    | ✅   | 端口号（传 0 使用该类型默认端口） |
| `database` | String | ✅   | 数据库名称                        |
| `username` | String | ✅   | 数据库用户名                      |
| `password` | String | ✅   | 数据库密码                        |

### 工具列表

| 工具名称          | 描述                                                  | 特有参数              |
| ----------------- | ----------------------------------------------------- | --------------------- |
| `listTables`      | 列出数据库中的所有表                                  | `schema`（可选）      |
| `describeTable`   | 获取指定表的列信息（字段、类型、主键、自增等）        | `table`, `schema`（可选） |
| `listIndexes`     | 获取指定表的索引信息                                  | `table`, `schema`（可选） |
| `executeQuery`    | 执行只读 SQL（SELECT/SHOW/DESCRIBE/EXPLAIN）          | `sql`, `limit`（可选，默认100） |
| `executeUpdate`   | 执行写操作（INSERT/UPDATE/DELETE/DDL）                | `sql`                 |
| `getDatabaseInfo` | 获取数据库元数据（产品名、版本、驱动、特性等）        | —                     |

### 示例：AI 调用 listTables

当 AI 客户端需要列出本地 MySQL 数据库的表时，它会调用：

```
Tool: listTables
  type     = "mysql"
  host     = "localhost"
  port     = 3306
  database = "mydb"
  username = "root"
  password = "****"
```

---

## 集成到 AI 客户端

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-db-server": {
      "type": "sse",
      "url": "http://localhost:8088/sse"
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "mcp-db-server": {
      "transport": "sse",
      "url": "http://localhost:8088/sse"
    }
  }
}
```

### Trae

在 Trae 的 MCP 设置中添加：

```json
{
  "mcpServers": {
    "mcp-db-server": {
      "transport": "sse",
      "url": "http://localhost:8088/sse"
    }
  }
}
```

> **注意**：不同客户端使用的 SSE 端点路径可能不同。本项目配置的 SSE 端点为 `/sse`，所有客户端统一使用 `http://localhost:8088/sse` 连接。

---

## 项目结构

```
mcp-db-server/
├── src/main/java/com/mcp/db/
│   ├── McpDbServerApplication.java      # 启动类
│   ├── config/
│   │   └── ConnectionFactory.java        # 动态连接工厂（含连接池缓存）
│   └── tool/
│       └── DatabaseTools.java            # MCP 工具方法（@Tool 注解）
├── src/main/resources/
│   └── application.yml                   # 应用配置（仅服务端口和 MCP 设置）
├── sql/init/
│   └── 01-init-demo.sql                  # MySQL 示例初始化数据
├── Dockerfile                            # Docker 镜像构建
├── docker-compose.yml                    # 一键部署（含 MySQL 示例）
├── .env.example                          # 环境变量模板
├── pom.xml                               # Maven 依赖管理
└── LICENSE
```

---

## 开发指南

### IDE 配置

推荐使用 **IntelliJ IDEA**。

### 构建

```bash
# 编译
./mvnw compile

# 运行测试
./mvnw test

# 打包
./mvnw clean package -DskipTests
```

### 添加新数据库支持

1. 在 `ConnectionFactory.java` 中：
   - `DEFAULT_PORTS` 添加默认端口映射
   - `DRIVER_CLASSES` 添加 JDBC 驱动类映射
   - `buildJdbcUrl()` 添加 JDBC URL 构建逻辑
2. 在 `pom.xml` 中添加对应的 JDBC 驱动依赖
3. 更新本文档中"支持的数据库"表格

欢迎提交 PR！

---

## 贡献

请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何参与贡献。

---

## License

本项目基于 [MIT License](LICENSE) 开源。

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PerfectXM](https://github.com/PerfectXM)
- **Source:** [PerfectXM/mcp-db-server](https://github.com/PerfectXM/mcp-db-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-perfectxm-mcp-db-server
- Seller: https://agentstack.voostack.com/s/perfectxm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.