DatabaseMcpServer-simple 1.0.0

DatabaseMCP 数据库操作服务器

🇺🇸 English | 🇨🇳 中文 | 🌐 官网

一个功能强大的数据库操作 MCP (Model Context Protocol) 服务器，聚焦 MySQL、PostgreSQL、SQL Server、Oracle、MongoDB 五种主流数据库类型，支持 单实例多数据库动态切换，让 AI 助手能够安全、便捷地执行只读数据库查询。

✨ 核心特性

• 🗄️ 多数据库支持 - 仅支持 MySQL、PostgreSQL、SQL Server、Oracle、MongoDB

• 🔄 单实例多数据库 - 一个 MCP Server 实例可配置和动态切换多个数据库连接

• 🔒 安全防护 - 危险操作检测 + SQL 注入防护 + 敏感信息保护

• ⚡ 高性能优化 - SqlSugarScope 连接池复用 + 数据库特定优化

• 🔧 灵活配置 - 支持 JSON 配置文件，轻松管理多数据库连接

• 🧭 只读查询 - 提供连接管理、架构查询与只读 SQL 查询工具

• 📦 .NET Global Tool - 简单安装，一键部署

• 🌐 跨平台 - Windows、macOS、Linux 全面支持\n## 🗄️ 支持的数据库类型

• MySQL (默认)

• PostgreSQL

• SQL Server

• Oracle

• MongoDB\n\n## 🚀 快速开始

第一步：安装 .NET Global Tool

# 安装最新版本
dotnet tool install --global DatabaseMcpServer-simple

# 验证安装
DatabaseMcpServer-simple --version

第二步：创建数据库配置文件

创建 databases.json 配置文件：

{
  "databases": [
    {
      "name": "default",
      "connectionString": "Server=localhost;Database=test;Uid=root;Pwd=123456;",
      "dbType": "MySql",
      "description": "默认数据库",
      "isDefault": true
    }
  ]
}

第三步：配置 MCP 客户端

创建 mcp.json 配置文件（VS Code: .vscode/mcp.json）:

{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer-simple",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

第四步：测试连接并执行查询

重启 IDE 后，在 AI 助手中测试：

"测试数据库连接"

系统返回：

{
  "success": true,
  "connected": true,
  "databaseType": "MySql"
}

📦 安装方式

方式 1：.NET Global Tool（推荐）

安装：

dotnet tool install --global DatabaseMcpServer-simple
# 更新：dotnet tool update --global DatabaseMcpServer-simple

MCP 配置：

{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer-simple",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

方式 2：dnx 命令

安装：

dnx DatabaseMcpServer-simple@1.0.0 --yes

MCP 配置：

{
  "mcpServers": {
    "database": {
      "command": "dnx",
      "args": ["DatabaseMcpServer-simple@1.0.0", "--yes"],
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

方式 3：本地源码运行

运行：

git clone https://github.com/ttcc666/DatabaseMcpServer.git
cd DatabaseMcpServer
dotnet run

MCP 配置：

{
  "mcpServers": {
    "database": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/DatabaseMcpServer"],
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

⚙️ 配置指南

DatabaseMcpServer-simple 1.0.0 统一使用 JSON 配置文件管理数据库连接。

配置文件方式（必需）

通过环境变量 DB_CONFIG_PATH 指定配置文件的绝对路径：

MCP 配置示例：

{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer-simple",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

配置文件格式 (databases.json)：

{
  "databases": [
    {
      "name": "mysql-main",
      "connectionString": "Server=localhost;Database=myapp;User=root;Password=123456;",
      "dbType": "MySql",
      "description": "MySQL 主库",
      "isDefault": true,
      "optimizationSettings": {`n        "enableBulkCopy": "true",`n        "maxPoolSize": "100"`n      }
    },
    {
      "name": "postgres-analytics",
      "connectionString": "Host=localhost;Database=analytics;Username=postgres;Password=123456;",
      "dbType": "PostgreSQL",
      "description": "PostgreSQL 分析库",
      "optimizationSettings": {
        "autoToLower": "true",
        "enableIlike": "true"
      }
    }
  ]
}

多数据库管理工具：

• list_databases - 列出所有可用的数据库连接
• switch_database - 切换到指定的数据库
• get_current_database - 获取当前活动的数据库
• test_connection_by_name - 测试指定数据库的连接

性能优化工具：

• health_check - 对所有数据库连接执行健康检查（响应时间、连接状态）
• test_connection_with_retry - 带自动重试的连接测试（指数退避策略）

---

🌐 环境配置

必需环境变量

• DB_CONFIG_PATH: 数据库配置文件路径（必需）
  • 示例: D:\config\databases.json

可选环境变量

• SEQ_SERVER_URL: Seq 日志服务器地址（可选）
• SEQ_API_KEY: Seq API 密钥（可选）
• DB_DDL_WHITELIST: DDL 操作白名单（可选，分号分隔的正则表达式）

数据库特定优化配置

从 1.0.0 版本开始，所有数据库特定优化配置都在 databases.json 的 optimizationSettings 中设置。

详细配置文档：

• MySQL 配置指南
• PostgreSQL 配置指南
• SQL Server 配置指南
• Oracle 配置指南
• MongoDB 配置指南
• 配置索引\n---

🔄 从旧版本迁移到 1.0

⚠️ 破坏性变更

DatabaseMcpServer-simple 1.0.0 移除了环境变量配置方式，统一使用 JSON 配置文件。

迁移步骤

1. 单数据库配置迁移

旧方式（1.x - 已废弃）:

{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer-simple",
      "env": {
        "DB_CONNECTION_STRING": "Server=localhost;Database=test;...",
        "DB_TYPE": "MySql",
        "DB_DM_LOWERCASE_TABLES": "true"
      }
    }
  }
}

新方式（1.0）:

1. 创建 databases.json 文件：

{
  "databases": [
    {
      "name": "default",
      "connectionString": "Server=localhost;Database=test;...",
      "dbType": "MySql",
      "description": "默认数据库",
      "isDefault": true,
      "optimizationSettings": {
        "lowercaseTables": "true"
      }
    }
  ]
}

2. 更新 MCP 配置：

{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer-simple",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

2. 环境变量映射表

旧环境变量	新 JSON 配置路径
DB_CONNECTION_STRING	databases[].connectionString
DB_TYPE	databases[].dbType
DB_DM_LOWERCASE_TABLES	databases[].optimizationSettings.lowercaseTables
DB_KDBNDP_MODE	databases[].optimizationSettings.mode
DB_GAUSSDB_NATIVE_DRIVER	databases[].optimizationSettings.nativeDriver
DB_ORACLE_CAMEL_CASE	databases[].optimizationSettings.camelCase
DB_POSTGRES_AUTO_TO_LOWER	databases[].optimizationSettings.autoToLower
DB_SQLITE_ENABLE_DEFAULT_VALUE	databases[].optimizationSettings.enableDefaultValue
DB_DISABLE_NVARCHAR	databases[].optimizationSettings.disableNvarchar

完整映射表请参考各数据库配置文档。

3. 自动迁移检测

如果您仍在使用旧的环境变量配置，DatabaseMcpServer-simple 1.0.0 会自动检测并显示详细的迁移提示。

常用数据库连接字符串示例

数据库	连接字符串示例	详细文档
MySQL	Server=localhost;Port=3306;Database=mydb;User=root;Password=123456;	MySQL.md
PostgreSQL	Host=localhost;Port=5432;Database=mydb;Username=postgres;Password=123456;	PostgreSQL.md
SQL Server	Server=localhost;Database=mydb;User Id=sa;Password=123456;	SQLServer.md
Oracle	Data Source=localhost/orcl;User ID=system;Password=oracle123;	Oracle.md
MongoDB	mongodb://localhost:27017/mydb	MongoDB.md	\n当前工具仅包含：

• 连接与配置管理
• 架构只读查询
• 只读 SQL 查询

完整工具列表请参考 TOOLS.md 或 .mcp/server.json。

💡 使用示例

示例 1：基础连接与查询

测试数据库连接

测试数据库连接

列出所有表

列出当前数据库的所有表

查询用户数据

查询 users 表中的所有数据

示例 2：参数化查询

条件查询

查询 users 表中年龄大于 25 岁的活跃用户，按创建时间倒序排列

IN 参数查询

查询用户ID在 [1,2,3,4,5] 中的用户信息

多条件查询

查询城市为"北京"、年龄在 20-30 之间、状态为活跃的用户

示例 3：数据统计与分析

聚合查询

统计 products 表中每个分类的商品数量和平均价格

多结果集查询

同时查询：1) 用户总数和活跃用户数量 2) 最近 7 天的订单数据

标量值查询

获取订单表中订单状态为"已完成"的总金额

示例 4：架构查询

获取表结构

获取 orders 表的完整结构信息：列、主键、索引、自增列等

查询索引信息

查询 users 表的所有索引信息

检查表是否存在

检查数据库中是否存在名为"user_logs"的表

🔒 安全特性

危险操作检测

系统自动检测并阻止以下危险操作：

• DROP TABLE / DROP DATABASE - 删除表/数据库
• TRUNCATE TABLE - 清空表数据
• ALTER TABLE - 修改表结构
• 无 WHERE 条件的 DELETE / UPDATE

危险操作会被直接阻止；如需执行 DDL 或写入，请在数据库客户端中完成，并谨慎评估风险。

SQL 注入防护

所有查询都支持参数化查询，自动防止 SQL 注入：

{
  "sql": "SELECT * FROM users WHERE age > @age AND city = @city",
  "parameters": "{\"age\":18,\"city\":\"北京\"}"
}

敏感信息保护

• 连接字符串中的密码自动隐藏（显示为 Password=****）
• 日志中不输出完整连接字符串
• 配置信息返回时自动脱敏

💻 开发指南

本地开发

# 克隆项目
git clone https://github.com/ttcc666/DatabaseMcpServer.git
cd DatabaseMcpServer

# 创建配置文件 databases.json 后运行
DB_CONFIG_PATH="path/to/databases.json" dotnet run

# 构建项目
dotnet build

# 运行测试
dotnet test

# 打包发布
dotnet pack -c Release

🆕 版本发布

• 1.0.0
  • 版本号统一至 1.0.0（徽标/示例命令/配置）
  • 为工具、服务、策略等补充中文 XML 注释，便于智能提示与维护
  • 精简冗余工具接口（多型标量/重复查询/重复 DML 包装），保持核心能力
  • 修复模型非空属性警告，构建无警告

添加新工具

1. 创建工具类文件

   # 在 Tools/ 目录下创建新工具类
   # Management/ - 连接和架构管理
   # Query/ - 查询工具
   

2. 实现工具类

   using System.ComponentModel;
   using ModelContextProtocol.Server;
   using DatabaseMcpServer.Interfaces;
   
   namespace DatabaseMcpServer.Tools;
   
   internal class YourNewTools
   {
       private readonly IDatabaseConfigService _databaseConfig;
       private readonly IDatabaseHelperService _databaseHelper;
   
       public YourNewTools(IDatabaseConfigService databaseConfig, IDatabaseHelperService databaseHelper)
       {
           _databaseConfig = databaseConfig;
           _databaseHelper = databaseHelper;
       }
   
       [McpServerTool]
       [Description("你的工具描述")]
       public string YourMethod([Description("参数描述")] string parameter)
       {
           using var db = _databaseConfig.CreateClient();
           // 实现你的功能
           return _databaseHelper.SerializeResult(new { success = true, data = "result" });
       }
   }
   

3. 注册工具 在 Program.cs 中：

   builder.Services
       .AddMcpServer()
       .WithStdioServerTransport()
       .WithTools<ConnectionTools>()
       .WithTools<SchemaTools>()
       .WithTools<QueryTools>()
       .WithTools<YourNewTools>(); // 添加你的工具
   

项目架构

MCP Protocol Layer (stdio)
    ↓
Tools Layer (Connection/Schema/Query)
    ↓
Services Layer (DatabaseConfigService)
    ↓
Data Access Layer (SqlSugar ORM)

关键组件：

• DatabaseConfigService - 配置管理和连接创建
• DatabaseHelper - 数据库类型解析和安全检查
• McpExceptionFilter - 统一异常处理
• ApiResult<T> - 标准化返回格式

🛠️ 技术栈

• .NET 9.0 - 最新的 .NET 平台
• ModelContextProtocol 0.4.0 - MCP 协议 C# SDK
• SqlSugarCore 5.1.4 - 轻量级高性能 ORM
• Serilog - 结构化日志框架
• Microsoft.Extensions.Hosting - 依赖注入和托管

📚 相关资源

• MCP 官方文档
• MCP GitHub
• SqlSugar 文档
• VS Code MCP 指南

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建特性分支：git checkout -b feature/AmazingFeature
3. 提交更改：git commit -m 'Add AmazingFeature'
4. 推送到分支：git push origin feature/AmazingFeature
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

⚠️ 免责声明

• 本项目已发布 1.0.0 正式版本
• 1.0.0 版本包含破坏性变更，请参考迁移指南
• 生产环境使用前请充分测试
• 定期备份重要数据
• 注意配置中的敏感信息保护

---

DatabaseMCP - 让 AI 助手轻松操作数据库！