Streamable Db MCP Server

MySQL MCP服务器

Rust中的可流式MySQL MCP（模型上下文协议）服务器实现，提供数据库连接和查询执行功能。

快速开始

🐳 Docker部署（推荐）

最简单的入门方法是使用Docker和附带的MySQL数据库：

# Clone the repository
git clone https://github.com/Sparrow2025/streamable-db-mcp-server.git
cd streamable-db-mcp-server

# Start with Docker (includes MySQL database)
./docker/start.sh

# Test the deployment
./docker/test.sh

这将启动MCP服务器和带有示例数据的MySQL数据库。

可用网址：

• MCP服务器： http://localhost:8080/mcp
• 健康检查： http://localhost:8080/health
• MySQL数据库： localhost:3306 （用户： mcp_user，密码： mcp_password)

有关更多Docker选项，请参阅 .

🛠️ 地方发展

如果你更喜欢在没有Docker的情况下在本地运行：

先决条件

• 锈蚀1.70+
• MySQL 5.7+或MariaDB 10.3+

设置

# Copy configuration template
cp config.example.toml config.toml

# Edit config.toml with your database credentials
# Then build and run
cargo build --release
cargo run

配置

服务器支持通过TOML文件进行配置，并回退到环境变量。新的配置格式将数据库连接详细信息分为单独的字段，以提高清晰度和安全性。

配置文件

创建 config.toml 项目根目录中的文件：

[server]
# Server listening port
port = 8080
# Log level: trace, debug, info, warn, error
log_level = "info"

[database]
# Database connection details
host = "localhost"          # Database host
port = 3306                 # Database port (optional, default: 3306)
username = "root"           # Database username
password = "password"       # Database password
database = "myapp"          # Database name
# Connection timeout in seconds (optional, default: 30)
connection_timeout = 30
# Maximum number of connections in the pool (optional, default: 10)
max_connections = 10

[mcp]
# MCP protocol version
protocol_version = "2024-11-05"
# Server identification
server_name = "mysql-mcp-server"
server_version = "0.1.0"

配置选项

数据库部分

• host：MySQL服务器主机名或IP地址
• port：MySQL服务器端口（可选，默认：3306）
• username：数据库用户名
• password：数据库密码
• database：要连接的数据库名称
• connection_timeout：连接超时（秒）（可选，默认值：30）
• max_connections：池中的最大连接数（可选，默认值：10）

服务器部分

• port：HTTP服务器侦听端口（默认值：8080）
• log_level：日志记录级别（跟踪、调试、信息、警告、错误）

MCP部分

• protocol_version：MCP协议版本
• server_name：服务器标识名称
• server_version：服务器版本字符串

配置文件位置

服务器将按以下顺序查找配置文件：

1. config.toml （当前目录）
2. ./config.toml
3. config/config.toml

环境变量（回退）

如果找不到配置文件，服务器将使用环境变量：

# Individual database components (preferred)
export DB_HOST="localhost"
export DB_PORT=3306
export DB_USERNAME="root"
export DB_PASSWORD="password"
export DB_DATABASE="myapp"

# Or use DATABASE_URL (legacy support)
export DATABASE_URL="mysql://username:password@localhost:3306/database"

# Server configuration
export PORT=8080
export LOG_LEVEL=info

快速开始

自动设置（推荐）

运行安装脚本以自动配置所有内容：

./setup-mcp.sh

此脚本将：

• 构建项目
• 创建 config.toml 从示例中
• 生成MCP客户端配置
• 提供后续步骤

手动设置

1. 复制示例配置：

   cp config.example.toml config.toml

1. 编辑配置：

更新中的数据库连接详细信息 config.toml:

   [database]
   host = "your-mysql-host"
   port = 3306
   username = "your-username"
   password = "your-password"
   database = "your-database-name"

1. 构建并运行服务器：

   cargo build --release
   cargo run

1. 测试配置：

   ./test-mcp-connection.sh

1. 测试HTTP终结点（启动服务器后）：

   # In one terminal, start the server:
   cargo run --release

   # In another terminal, test the endpoints:
   ./test-http-endpoints.sh

1. 配置您的MCP客户端 （参见 MCP客户端配置 部分）

发展

运行测试

# Run unit tests (no database required)
cargo test --lib

# Run integration tests (requires TEST_DATABASE_URL)
export TEST_DATABASE_URL="mysql://root:password@localhost:3306/test_db"
cargo test

# Run all tests
cargo test

测试数据库设置

对于集成测试，您可以使用Docker设置MySQL实例：

# Start MySQL container
docker run --name mysql-test \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=test_db \
  -p 3306:3306 \
  -d mysql:8.0

# Set test database URL
export TEST_DATABASE_URL="mysql://root:password@localhost:3306/test_db"

# Run tests
cargo test

特性

• 可流式HTTP传输：使用rmcp进行高效的数据传输
• 只读查询执行：支持SELECT、SHOW、DESCRIBE、EXPLAIN操作（出于安全考虑，写入操作被阻止）
• 数据库探索：列出数据库、表并检查表结构
• 结果流：通过增量交付处理大型结果集
• 安全：只允许只读查询（INSERT、UPDATE、DELETE被阻止）
• 错误处理：全面的错误报告和记录
• 配置管理：灵活的基于TOML的配置
• 基于属性的测试：使用proptest进行稳健测试

MCP客户端配置

这是一个 流式HTTP MCP服务器 它作为HTTP服务运行。MCP客户端通过HTTP端点而不是stdio连接到它。

服务器端点

运行后，服务器提供以下HTTP端点：

• MCP协议: http://localhost:8080/mcp （基于HTTP的JSON-RPC）
• 流媒体查询: http://localhost:8080/stream/query （服务器发送的事件）

Kiro IDE配置

1. 启动MySQL MCP服务器:

   cargo run --release

服务器将于启动 http://localhost:8080 默认情况下。

1. 配置Kiro IDE (.kiro/settings/mcp.json):

{
  "mcpServers": {
    "mysql-server": {
      "url": "http://localhost:8080/mcp",
      "disabled": false,
      "autoApprove": ["test_connection"]
    }
  }
}

Claude桌面配置

备注：Claude Desktop可能还不支持基于HTTP的MCP服务器。查看最新的Claude Desktop文档以了解HTTP MCP支持。

如果支持，配置将是：

{
  "mcpServers": {
    "mysql-server": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

手动HTTP测试

您可以直接使用HTTP请求测试服务器：

# Test connection
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "test_connection",
      "arguments": {}
    }
  }'

# Execute a query
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", 
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "execute_query",
      "arguments": {
        "sql": "SELECT 1 as test"
      }
    }
  }'

测试HTTP服务器

您可以在配置MCP客户端之前直接测试服务器：

# 1. Start the server
cargo run --release

# 2. In another terminal, test the endpoints:

# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1, 
    "method": "tools/list"
  }'

# Test database connection
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "test_connection",
      "arguments": {}
    }
  }'

可用的MCP工具

配置后，您的MCP客户端将提供以下工具：

1. test_connection

测试数据库连接。

参数：无

示例用法:

Test the MySQL database connection

2. execute_query

对数据库执行只读SQL查询。出于安全原因，只允许使用SELECT、SHOW、DESCRIBE和EXPLAIN语句。

参数:

• sql （string）：要执行的只读SQL查询（仅限SELECT、SHOW、DESCRIBE、EXPLAIN）
• parameters （数组，可选）：查询已准备语句的参数
• stream_results （boolean，可选）：是否流式传输大型结果集

示例用法:

Execute this SQL query: SELECT * FROM users WHERE age > 25
Show me all tables: SHOW TABLES
Describe table structure: DESCRIBE users

安全说明：出于安全原因，写操作（INSERT、UPDATE、DELETE、DROP、CREATE、ALTER）被阻止。

3. streaming_query

对大型结果集执行具有流式支持的查询。

参数:

• sql （string）：要执行的SQL查询
• parameters （数组，可选）：查询参数

示例用法:

Stream results from: SELECT * FROM large_table ORDER BY created_at

配置提示

1. 自动批准工具：添加常用工具 autoApprove 跳过确认提示
2. 工作目录：设置 cwd 到包含您的 config.toml 文件
3. 环境变量：使用 env 如果不使用配置文件，则设置数据库凭据
4. 日志记录：设置 RUST_LOG=debug 用于开发过程中的详细日志记录

MCP会话示例

配置后，您可以通过自然语言与MySQL数据库交互：

User: "Show me all users from the database"
Assistant: I'll query the users table for you.
[Executes: SELECT * FROM users]

User: "Create a new user named John with email john@example.com"
Assistant: I'll insert a new user record.
[Executes: INSERT INTO users (name, email) VALUES ('John', 'john@example.com')]

User: "Show me the total count of orders by status"
Assistant: I'll get the order counts grouped by status.
[Executes: SELECT status, COUNT(*) as count FROM orders GROUP BY status]

安全

此MCP服务器的设计考虑了安全性：

• 只读操作：只允许使用SELECT、SHOW、DESCRIBE和EXPLAIN查询
• 写入操作被阻止：INSERT、UPDATE、DELETE、DROP、CREATE、ALTER操作被拒绝
• SQL注入保护：所有查询在执行前都经过验证
• 连接安全性：使用具有适当身份验证的安全数据库连接

配置安全

⚠️ 重要安全注意事项:

• 永不承诺 config.toml -它包含敏感的数据库凭据
• 这 .gitignore 文件已配置为排除 config.toml 以及其他敏感文件
• 使用 config.example.toml 作为配置的模板
• 考虑在生产部署中使用环境变量
• 确保您的数据库用户具有所需的最小权限（建议为只读）

允许的SQL操作

✅ 允许:

• SELECT -查询数据
• SHOW -显示数据库元数据（表、数据库等）
• DESCRIBE / DESC -显示表格结构
• EXPLAIN -查询执行计划

❌ 已屏蔽:

• INSERT, UPDATE, DELETE -数据修改
• CREATE, ALTER, DROP -架构更改
• TRUNCATE -数据删除
• GRANT, REVOKE -权限更改
• 任何其他写入操作

MCP协议合规性

服务器实现了模型上下文协议（MCP）规范，并提供了以下工具：

• 数据库连接测试
• 只读SQL查询执行
• 数据库和表探索
• 大型数据集的结果流
• 错误处理和报告

许可证

该项目根据MIT许可证获得许可。