← Discover MCPs and Agents
D
MCPData & AnalyticsGitHub

DatabaseMcpServer

Links

Repository

README

From the repo.

DatabaseMCP 数据库操作服务器

NuGet .NET Tool License

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

一个功能强大的数据库操作 MCP (Model Context Protocol) 服务器，聚焦 19 种常用数据库类型（主流 + 特定场景 + 国产化/信创），支持 单实例多数据库动态切换，让 AI 助手能够安全、便捷地执行数据库操作。

✨ 核心特性

  • 🗄️ 多数据库支持 - 覆盖 17 种常用数据库（MySQL/PG/SQLServer/Oracle/MongoDB + SQLite/ClickHouse/TiDB/OceanBase + 达梦/人大金仓/华为 GaussDB/PolarDB/Vastbase/瀚高/神通/GoldenDB）
  • 🔄 单实例多数据库 - 一个 MCP Server 实例可配置和动态切换多个数据库连接
  • 🔒 安全防护 - 危险操作检测 + SQL 注入防护 + 敏感信息保护
  • ⚡ 高性能优化 - SqlSugarScope 连接池复用 + 数据库特定优化 + 自动性能调优
  • 🔧 灵活配置 - 支持 JSON 配置文件，轻松管理多数据库连接
  • 💾 完整功能 - 50+ MCP 工具（当前约 55 个），涵盖查询、操作、架构管理、健康检查等
  • 🚀 生产就绪 - 支持事务、批量操作、存储过程、自动重连
  • 📦 .NET Global Tool - 简单安装，一键部署
  • 🌐 跨平台 - Windows、macOS、Linux 全面支持

🗄️ 支持的数据库类型

🔥 一线最常用

  • MySQL (默认)
  • PostgreSQL
  • SQL Server
  • Oracle
  • MongoDB

📊 特定场景常用

  • SQLite
  • ClickHouse
  • TiDB
  • OceanBase
  • IBM DB2（已移除）
  • SAP HANA（已移除）

🇨🇳 国产化/信创

  • 达梦数据库 (dm)
  • 人大金仓 (kdbndp/kingbase)
  • 华为 GaussDB / OpenGauss
  • PolarDB (polardb)
  • 海量数据库 (vastbase)
  • 瀚高数据库 (hg)
  • 神通数据库 (oscar)
  • GoldenDB (goldendb)

🚀 快速开始

第一步：安装 .NET Global Tool

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

# 验证安装（CLI 本身没有 --version 参数；传入会得到退出码 2）
dotnet tool list --global | Select-String databasemcpserver

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

创建 databases.json 配置文件：

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

enableMonitorConfig 为可选根字段，默认 false。设为 true 后，长驻 MCP stdio / -web 会监听该文件，并在默认库变化时切换运行时当前库。优先级见下方配置文件监听。

💡 如果未在 MCP 客户端配置中设置 DB_CONFIG_PATH，stdio 模式会自动读取 %USERPROFILE%/.database-mcp/databases.json；CLI / -web 会额外在当前目录检查 ./databases.json 和 ./local-databases.json。显式设置仍是推荐做法。

第三步：配置 MCP 客户端

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

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

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

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

"测试数据库连接"

系统返回：

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

💻 命令行模式（CLI）

从当前版本开始，DatabaseMcpServer 在保留原有 MCP stdio 模式的同时，也支持直接从命令行做两类事情：

  • 无参数：启动 stdio MCP server（兼容现有 MCP 客户端配置）
  • -web：启动 localhost Web 配置管理页，并默认自动打开浏览器
  • tool 子命令：直接调用已暴露的 MCP tool
  • init / config 子命令：初始化并维护本地 databases.json

基本用法

# 启动本地 Web 配置页（默认自动打开浏览器）
DatabaseMcpServer -web
DatabaseMcpServer -web --config "D:\config\databases.json" --no-browser

# 启动 stdio MCP / -web，并在本进程启用或关闭配置文件监听
DatabaseMcpServer --enable-monitor-config
DatabaseMcpServer --enable-monitor-config true
DatabaseMcpServer --enable-monitor-config false -web --no-browser
DatabaseMcpServer -web --enable-monitor-config true --no-browser

# 初始化默认配置文件（默认写到 %USERPROFILE%/.database-mcp/databases.json）
DatabaseMcpServer init

# 查看 / 管理本地连接配置
DatabaseMcpServer config list
DatabaseMcpServer config presets
DatabaseMcpServer config preset --db-type Sqlite
DatabaseMcpServer config create --from-preset Sqlite --name sqlite-local --connection-string "Data Source=./data/local.db;Cache=Shared;Mode=ReadWriteCreate;" --description "local sqlite" --set-default
DatabaseMcpServer config create --from-preset Sqlite --name sqlite-preview --print-only
DatabaseMcpServer config add --name sqlite-local --db-type Sqlite --connection-string "Data Source=./data/local.db;Cache=Shared;Mode=ReadWriteCreate;" --set-default
DatabaseMcpServer config rename --name sqlite-local --new-name sqlite-dev
DatabaseMcpServer config update --name sqlite-dev --description "dev sqlite" --set-default
DatabaseMcpServer config validate
DatabaseMcpServer config clone --name sqlite-dev --new-name sqlite-ci
DatabaseMcpServer config doctor
DatabaseMcpServer config export --output ".\\backup-databases.json"
DatabaseMcpServer config import --input ".\\backup-databases.json" --config "D:\config\databases.json" --force

# 列出所有可调用的 tool
DatabaseMcpServer tool list

# 查看某个 tool 的帮助
DatabaseMcpServer tool help switch_database

# 直接调用 tool
DatabaseMcpServer tool list_databases --config "D:\config\databases.json"
DatabaseMcpServer tool get_table_schema --table-name users --config "D:\config\databases.json"

参数规则

  • -web 主要用于本地可视化配置管理
    • 默认绑定 localhost / 127.0.0.1，不对公网暴露
    • 默认沿用 CLI 配置解析顺序：--config -> ./databases.json -> ./local-databases.json -> DB_CONFIG_PATH -> %USERPROFILE%/.database-mcp/databases.json
    • 如果没有找到现有配置文件，则回退到 %USERPROFILE%/.database-mcp/databases.json 作为可写目标
    • 页面同时管理两套状态：databases.json 中的默认连接，以及 %USERPROFILE%/.database-mcp/cli-state.json 中的当前连接
    • --port <number> 可显式指定端口；不传则自动分配可用端口
    • --no-browser 可禁用自动打开浏览器
    • --enable-monitor-config true|false 可在本进程强制开启或关闭 databases.json 监听，优先级高于环境变量和配置文件
  • init / config 主要用于本地配置管理
    • 默认操作 %USERPROFILE%/.database-mcp/databases.json
    • 可以用 --config <path> 临时覆盖目标配置文件
    • config use / config set-default 用来切换默认连接（写回 databases.json）
    • config rename / config update 用来演进已有连接
    • config validate 用来做配置文件层校验（不是连通性测试）
    • config clone 用来快速复制连接
    • config presets / config preset 用来查看内置连接模板
    • config create --from-preset 用来直接基于模板生成连接骨架，也可顺手覆盖连接串/描述
    • config update --clear-description 用来显式清空说明
    • --enable-dangerous-operations true|false 可在 config create/add/update 中写入危险操作开关（默认 false）
    • config doctor 用来做诊断，默认会测试各连接连通性，并给出修复建议；--summary-only 适合脚本
    • config export / config import 用来备份和迁移配置文件
  • tool 名称与 MCP 中保持一致，使用 snake_case
    • 例如：list_databases、get_table_schema、execute_command
  • tool 参数统一映射为 kebab-case 选项
    • 例如：databaseName -> --database-name
    • 例如：initialDelayMs -> --initial-delay-ms
  • tool switch_database 用来切换当前连接
    • CLI 下会按“已解析 config 路径”持久化当前连接到 %USERPROFILE%/.database-mcp/cli-state.json
    • 不会修改 databases.json 里的默认连接
    • 后续 tool get_current_database / tool list_databases / 查询类命令都会继续使用这个当前连接
    • 只有在没有已保存当前连接，或保存的连接已失效时，才会回退到默认连接
  • CLI 全局选项：
    • --config <path>：本次调用临时指定配置文件
    • --yes：执行写操作 / 高风险 schema tool 时必须显式确认
    • --help：显示帮助

tool 模式下的配置文件查找顺序

如果执行的是 DatabaseMcpServer tool ...，且没有显式传 --config，CLI 会按以下顺序查找数据库配置：

  1. 当前目录 ./databases.json
  2. 当前目录 ./local-databases.json
  3. 环境变量 DB_CONFIG_PATH
  4. 用户目录 %USERPROFILE%/.database-mcp/databases.json

高风险命令确认

以下写操作 / 高风险命令必须追加 --yes：

DatabaseMcpServer tool drop_table --table-name users --config "D:\config\databases.json" --yes
DatabaseMcpServer tool execute_command --sql "delete from users where id = 1" --config "D:\config\databases.json" --yes

CLI 模式下，命令结果 JSON 输出到 stdout，帮助和日志输出到 stderr，便于脚本集成。 另外，tool switch_database 与 config use 语义不同：前者切换并持久化“当前连接”，后者修改配置文件中的“默认连接”。

详细命令说明见：

📦 安装方式

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

安装：

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

MCP 配置：

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

方式 2：dnx 命令

安装：

dnx DatabaseMcpServer@3.6.5 --yes

MCP 配置：

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

方式 3：本地源码运行

运行：

git clone https://github.com/ttcc666/DatabaseMcpServer.git
cd DatabaseMcpServer
# .NET 9
dotnet run --framework net9.0

# .NET 10
dotnet run --framework net10.0

MCP 配置：

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

⚙️ 配置指南

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

配置文件方式（推荐；未设置时自动发现）

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

自动发现优先级：

  • stdio 模式：DB_CONFIG_PATH → %USERPROFILE%/.database-mcp/databases.json（不读取当前目录，避免 MCP 客户端目录下的零散文件被误读）。
  • CLI / -web 模式：--config → ./databases.json → ./local-databases.json → DB_CONFIG_PATH → %USERPROFILE%/.database-mcp/databases.json。

显式设置 DB_CONFIG_PATH 仍是推荐做法。

MCP 配置示例：

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

当 databases.json 内容更新后，可以直接调用 reload_database_config，让 MCP 在不重启进程的情况下重新读取配置并刷新连接缓存。

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

{
  "enableMonitorConfig": false,
  "databases": [
    {
      "name": "mysql-main",
      "connectionString": "Server=localhost;Database=myapp;User=root;Password=123456;",
      "dbType": "MySql",
      "description": "MySQL 主库",
      "isDefault": true,
      "enableDangerousOperations": false,
      "optimizationSettings": {
        "enableCache": "true",
        "batchSize": "1000"
      }
    },
    {
      "name": "postgres-analytics",
      "connectionString": "Host=localhost;Database=analytics;Username=postgres;Password=123456;",
      "dbType": "PostgreSQL",
      "description": "PostgreSQL 分析库",
      "optimizationSettings": {
        "autoToLower": "true",
        "enableIlike": "true"
      }
    }
  ]
}

根级字段 enableMonitorConfig 可写入配置文件，控制长驻 MCP stdio / -web 是否监听该文件。省略时视为 false。

配置文件监听（可选）

长驻进程（MCP stdio / -web）可以监听 databases.json：文件里的默认库变化时，运行时当前库会跟着切换。一次性 tool / config 命令不会启用监听。

可通过以下来源配置，优先级从高到低：

优先级来源说明
1（最高）启动参数 --enable-monitor-config true|false仅对本进程生效，强制开启或关闭；不写回配置文件
2环境变量 ENABLE_MONITOR_CONFIGtrue/false（也接受 1/0/yes/no/on/off）；未设置时继续往下看
3配置文件 enableMonitorConfigdatabases.json 根字段；可直接编辑 JSON
4（默认）未配置关闭监听

示例：配置文件里写了 "enableMonitorConfig": true，但启动时带 --enable-monitor-config false 或环境变量 ENABLE_MONITOR_CONFIG=false，本进程仍不会监听。

多数据库管理工具：

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

性能优化工具：

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

🌐 环境配置

可选环境变量

  • DB_CONFIG_PATH: 数据库配置文件路径
    • 示例: D:\config\databases.json
    • 优先级: 环境变量DB_CONFIG_PATH → 用户目录%USERPROFILE%/.database-mcp/databases.json（stdio 模式）；CLI / -web 还会在当前目录查找 ./databases.json 和 ./local-databases.json
  • SEQ_SERVER_URL: Seq 日志服务器地址（可选）
  • SEQ_API_KEY: Seq API 密钥（可选）
  • DB_DDL_WHITELIST: DDL 操作白名单（可选，分号分隔的正则表达式）
  • ENABLE_MONITOR_CONFIG: 是否监听 databases.json 并让长驻 MCP / -web 跟随默认库变更（true/false，默认关闭）。也可在配置文件根级设置 "enableMonitorConfig": true。优先级：--enable-monitor-config > ENABLE_MONITOR_CONFIG > enableMonitorConfig。

数据库特定优化配置

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

详细配置文档：

🔄 从 1.x 迁移到 2.0

⚠️ 破坏性变更

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

迁移步骤

1. 单数据库配置迁移

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

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

新方式（2.0）:

  1. 创建 databases.json 文件：
{
  "databases": [
    {
      "name": "default",
      "connectionString": "Server=localhost;Database=test;...",
      "dbType": "MySql",
      "description": "默认数据库",
      "isDefault": true,
      "enableDangerousOperations": false,
      "optimizationSettings": {
        "lowercaseTables": "true"
      }
    }
  ]
}
  1. 更新 MCP 配置：
{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}

2. 环境变量映射表

旧环境变量新 JSON 配置路径
DB_CONNECTION_STRINGdatabases[].connectionString
DB_TYPEdatabases[].dbType
DB_DM_LOWERCASE_TABLESdatabases[].optimizationSettings.lowercaseTables
DB_KDBNDP_MODEdatabases[].optimizationSettings.mode
DB_GAUSSDB_NATIVE_DRIVERdatabases[].optimizationSettings.nativeDriver
DB_ORACLE_CAMEL_CASEdatabases[].optimizationSettings.camelCase
DB_POSTGRES_AUTO_TO_LOWERdatabases[].optimizationSettings.autoToLower
DB_SQLITE_ENABLE_DEFAULT_VALUEdatabases[].optimizationSettings.enableDefaultValue
DB_DISABLE_NVARCHARdatabases[].optimizationSettings.disableNvarchar

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

3. 自动迁移检测

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

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

数据库连接字符串示例详细文档
MySQLServer=localhost;Port=3306;Database=mydb;User=root;Password=123456;MySQL.md
PostgreSQLHost=localhost;Port=5432;Database=mydb;Username=postgres;Password=123456;PostgreSQL.md
SQL ServerServer=localhost;Database=mydb;User Id=sa;Password=123456;SQLServer.md
OracleData Source=localhost/orcl;User ID=system;Password=oracle123;Oracle.md
MongoDBmongodb://localhost:27017/mydbMongoDB.md
SQLiteData Source=mydb.db;SQLite.md
ClickHouseHost=localhost;Port=8123;User=default;Password=;Database=default;ClickHouse.md
TiDBServer=localhost;Port=4000;Database=mydb;User=root;Password=123456;TiDB.md
OceanBaseServer=localhost;Port=2881;Database=mydb;User=root@sys;Password=123456;OceanBase.md
OceanBase (Oracle 模式)Driver={OceanBase ODBC 2.0 Driver};Server=172.19.9.9;Port=2883;Database=TRD;User=USER@TENANT#CLUSTER:1650773680;Password=123456;Option=3;OceanBase.md
QuestDBhost=localhost;port=8812;username=admin;password=quest;database=qdb;ServerCompatibilityMode=NoTypeLoading;QuestDb.md
DuckDBDataSource=train_services.dbDuckDB.md
达梦数据库Server=localhost;Port=5236;Database=mydb;User=SYSDBA;Password=SYSDBA001;DM.md
人大金仓Server=localhost;Port=54321;Database=mydb;User=SYSTEM;Password=system123;Kdbndp.md
GBase 8sHost=localhost;Service=19088;Server=gbase01;Database=testdb;Protocol=onsoctcp;Uid=gbasedbt;Pwd=GBase123;Db_locale=zh_CN.utf8;Client_locale=zh_CN.utf8GBase.md
GaussDB / OpenGaussPORT=5432;DATABASE=mydb;HOST=localhost;PASSWORD=Gauss@123;USER ID=gaussdb;GaussDB.md
PolarDBServer=localhost;Port=3306;Database=mydb;User=root;Password=123456;PolarDB.md
VastbaseHost=localhost;Port=5432;Database=mydb;Username=vastbase;Password=123456;Vastbase.md
TDengineHost=localhost;Port=6030;Username=root;Password=taosdata;Database=powerTDengine.md
瀚高数据库Server=localhost;Port=5866;Database=mydb;Uid=highgo;Pwd=123456;HighGo.md
神通数据库Data Source=localhost;User Id=sysdba;Password=oracle;Oscar.md
GoldenDBServer=localhost;Port=1888;Database=mydb;Uid=golden;Pwd=123456;GoldenDB.md

更多连接字符串和优化配置请参考 DatabaseSetting/ 目录下的详细文档。

📋 完整功能清单（约 55 个工具）

逐工具参数、返回行为、CLI 示例和 --yes 要求见 TOOLS.md。

🔌 一、连接与配置管理

基础连接管理:

  • test_connection - 测试当前数据库连接
  • test_connection_by_name - 测试指定数据库的连接
  • get_database_config - 获取当前数据库配置信息
  • validate_configuration - 验证数据库配置是否正确
  • reload_database_config - 重新加载 databases.json 并刷新当前配置缓存

多数据库管理:

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

性能与健康检查:

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

🔍 二、数据库架构查询

  • get_data_base_list - 获取所有数据库名称
  • get_table_info_list - 获取所有表名
  • get_view_info_list - 查询所有视图
  • get_column_infos_by_table_name - 根据表名获取字段信息
  • get_table_schema - 获取表的完整结构信息
  • get_is_identities - 获取自增列
  • get_primaries - 获取主键
  • get_index_list - 获取所有索引名字集合
  • get_proc_list - 获取存储过程名字集合
  • get_func_list - 获取函数集合
  • get_trigger_names - 根据表名获取触发器集合

🔎 三、存在性检查

  • is_any_table - 判断表是否存在
  • is_any_column - 判断列是否存在
  • is_any_constraint - 判断约束是否存在
  • is_any_table_remark - 判断是否存在表描述

📊 四、数据查询工具

基础查询：

  • sql_query - 执行 SQL 查询并返回强类型实体集合（支持参数化查询，可选 commandTimeoutSeconds）
  • sql_query_single - 执行 SQL 查询并返回单条记录（可选超时）

高级查询：

  • get_data_set_all - 获取多个结果集，支持一次执行多个查询（可选超时）
  • sql_query_with_in_parameter - 处理 IN 参数查询，支持数组参数（可选超时）
  • batch_sql_query - 顺序执行 1-5 条只读 SQL，并逐条返回成功结果或错误（可选超时作用于批内每条）

标量值查询：

  • get_scalar - 获取首行首列的值（标量值，可选超时）

✏️ 五、数据操作工具

  • execute_command - 执行 SQL 命令（INSERT、UPDATE、DELETE；可选 commandTimeoutSeconds）
  • batch_execute_commands - 批量执行 SQL 命令（性能优化；可选超时作用于批内每条）
  • call_stored_procedure - 调用存储过程（简单用法；可选超时）
  • call_stored_procedure_with_output - 调用带有输出参数的存储过程（可选超时）
  • execute_command_with_go - 执行包含 GO 语句的 SQL Server 脚本（可选超时）

🛠️ 六、数据库架构操作（高风险）

表操作：

  • create_table - 创建表（使用列定义 JSON 数组）
  • drop_table - 删除表
  • truncate_table - 清空表
  • backup_table - 备份表
  • rename_table - 重命名表

列操作：

  • add_column - 添加列
  • update_column - 更新列
  • drop_column - 删除列
  • rename_column - 重命名列

约束和索引：

  • add_primary_key - 添加主键
  • drop_constraint - 删除约束
  • create_index - 创建索引或唯一约束

其他：

  • add_default_value - 添加默认值
  • add_table_remark - 添加表描述
  • add_column_remark - 添加列描述
  • delete_table_remark - 删除表描述
  • delete_column_remark - 删除列描述

完整工具列表请参考 .mcp/server.json

💡 使用示例

示例 1：基础连接与查询

测试数据库连接

测试数据库连接

列出所有表

列出当前数据库的所有表

查询用户数据

查询 users 表中的所有数据

示例 2：参数化查询

条件查询

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

IN 参数查询

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

多条件查询

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

示例 3：数据统计与分析

聚合查询

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

多结果集查询

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

标量值查询

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

示例 4：数据操作

插入新数据

向 products 表插入新商品：名称为"MacBook Pro M3"，价格为 14999，库存为 50

批量更新

批量更新以下用户的VIP状态：用户ID 1,3,5,7,9 设置为VIP，其他设置为普通用户

事务操作

执行转账操作：从账户A(ID:1001)转账 500 元到账户B(ID:1002)

示例 5：架构查询

获取表结构

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

查询索引信息

查询 users 表的所有索引信息

检查表是否存在

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

示例 6：存储过程调用

简单存储过程

调用存储过程 sp_monthly_report，传入参数年份 2025，月份 11

带输出参数的存储过程

调用存储过程 sp_user_statistics，传入用户ID 1001，获取该用户的订单总数和总金额

🔒 安全特性

危险操作检测

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

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

如需执行这些操作，建议优先使用专门的架构操作工具（如 create_table、drop_table、truncate_table 等），这些工具会明确提示风险。若确需通过 execute_command、execute_command_with_go 或 batch_execute_commands 执行 DDL，可在当前连接配置中显式设置 "enableDangerousOperations": true，或使用 config update --enable-dangerous-operations true 写入配置；默认值为 false。

兼容旧配置字段 allowDangerousOperations 和 CLI 参数 --allow-dangerous-operations。配置保存时统一写入 enableDangerousOperations；新旧 JSON 字段同时存在时，以新字段为准，与字段顺序无关。

SQL 注入防护

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

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

SQL 命令超时

查询与数据操作类工具支持可选参数 commandTimeoutSeconds（CLI：--command-timeout-seconds）：

  • 省略：使用 SqlSugar/驱动默认（通常 300 秒）
  • 0：无限等待
  • 合法范围：0–86400
  • 批处理工具上的超时作用于整批
{
  "sql": "SELECT * FROM large_report WHERE day = @day",
  "parameters": "{\"day\":\"2026-08-01\"}",
  "commandTimeoutSeconds": 900
}

DatabaseMcpServer tool execute_command \
  --sql 'update large_table set status=@status where id=@id' \
  --parameters '{"status":"done","id":1}' \
  --command-timeout-seconds 900 \
  --yes

完整参数说明见 TOOLS.md。

敏感信息保护

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

💻 开发指南

本地开发

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

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

# 或使用 .NET 10
DB_CONFIG_PATH="path/to/databases.json" dotnet run --framework net10.0

# 构建项目
dotnet build 'DatabaseMcpServer.slnx'

# 运行测试
dotnet test 'tests\DatabaseMcpServer.Tests\DatabaseMcpServer.Tests.csproj'

# 打包发布
dotnet pack 'src\DatabaseMcpServer\DatabaseMcpServer.csproj' -c Release

推荐的稳定验证方式：

.\scripts\verify.ps1

🆕 版本发布

  • 3.7.0

    • 新增可选配置文件监听，长驻 MCP stdio / -web 可在默认库变化时自动切换当前连接；优先级为启动参数 --enable-monitor-config > 环境变量 ENABLE_MONITOR_CONFIG > 配置字段 enableMonitorConfig，默认关闭
    • MCP stdio 未设置 DB_CONFIG_PATH 时，自动读取用户目录下的 .database-mcp/databases.json
    • 危险操作配置统一使用 enableDangerousOperations，兼容旧字段及 --allow-dangerous-operations 参数；新旧 JSON 字段同时存在时以新字段为准
    • 修复 Web 修改默认库后的运行时切换，并将配置路径测试隔离到临时用户目录

  • 3.6.6

    • 查询与数据操作类工具新增可选 commandTimeoutSeconds（CLI：--command-timeout-seconds），可覆盖默认约 300 秒超时
    • 指定超时通过 CopyNew() 隔离客户端，避免污染共享连接池；0 表示无限等待，合法范围 0–86400
    • 同步 TOOLS.md、CLI/skill 文档与单测覆盖

  • 3.6.5

    • 升级 ModelContextProtocol 到 2.0.0，并按新版本配置 ServerInfo 与工具 ReadOnly/Destructive/Idempotent 注解
    • 同步升级 Microsoft.Extensions.*、SqlSugarCore、Serilog.Sinks.Seq 与测试 SDK 到最新稳定版
    • 构建与 94 项单元测试通过（net9.0 / net10.0）

  • 3.6.0

    • 本地 Web 控制台新增中英文切换、界面文案国际化与语言偏好持久化
    • 使用应用级滚动容器并关闭弹层 body scroll lock，修复打开侧栏和下拉菜单时的界面抖动
    • 补充语言初始化与连接健康检查测试，并更新内嵌 production assets

  • 3.5.5

    • 修复 Oracle 连接检测执行 SELECT 1 时误报 ORA-00923 的问题
    • MCP 连接测试、健康检查、重试检测和 CLI doctor 统一使用方言无关连接探针
    • 补全 create_table 的 CLI 发布验证，覆盖全部 56 个 tools

  • 3.5.0

    • 新增 create_table 工具，支持通过列定义 JSON 创建数据表
    • 新增连接级 enableDangerousOperations 配置，默认关闭危险 SQL
    • 阻止无 WHERE 的 UPDATE / DELETE，并将执行客户端与安全策略绑定为同一配置快照

  • 3.0.0

    • Breaking：移除 Excel 导出和数据库文档生成 tools，同时移除 ClosedXML 依赖
    • 新增 batch_sql_query，支持一次顺序执行 1-5 条只读查询并逐项返回结果
    • 明确 batch_execute_commands 为非事务批处理，单项失败不会回滚此前成功的命令
    • 统一源码/测试目录到 src/ 与 tests/，修复 pooled SqlSugarScope 生命周期，并同步更新 CLI 文档与 skill

  • 2.5.0

    • 新增 -web 本地配置管理页，支持浏览器内维护 databases.json 与 cli-state.json
    • 前端重构为 Vue 3 + shadcn-vue 风格工作台，并补齐连接表格、编辑抽屉、诊断与导入导出交互
    • 修复 Web API fallback、非法 --port 崩溃和前端产物过期打包问题，补充对应测试覆盖

  • 2.1.1

    • 新增 reload_database_config，支持运行时重新加载 DB_CONFIG_PATH 指向的数据库配置
    • 刷新配置时同步清空客户端缓存，确保后续请求使用新的连接信息
    • 增补配置刷新与客户端重建测试，发版前验证覆盖更完整

  • 2.2.2

    • 修复 CLI 模式下 switch_database 仅在单次进程内生效的问题，改为按配置文件路径持久化“当前连接”
    • 新增状态恢复 / 配置路径隔离 / 失效连接回退默认连接的测试覆盖
    • 更新 NuGet / MCP manifest / README 版本元数据，便于 2.2.2 打包发布

  • 2.2.1

    • 收敛并优化 database-mcp-cli skill 的触发词、CLI 工作流说明与故障排查矩阵
    • 新增 agents/openai.yaml，补齐 UI metadata，使 skill 展示与触发语义一致
    • 更新 NuGet / MCP manifest / README 版本元数据，便于 2.2.1 打包发布

  • 2.2.0

    • 新增 CLI 模式：支持 DatabaseMcpServer tool <tool_name> 直接调用已有数据库工具
    • 保留无参数 stdio MCP server 兼容行为，并新增 tool list / tool help / --config / --yes
    • CLI 模式默认仅输出工具结果 JSON，避免日志污染 stdout
    • 补充 CLI 文档、全量 SQLite/SQL Server 验证脚本与 database-mcp-cli skill 草案

  • 2.1.0

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

添加新工具

  1. 创建工具类文件

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

  2. 实现工具类

    using System.ComponentModel;
using ModelContextProtocol.Server;
using DatabaseMcpServer.Interfaces;

namespace DatabaseMcpServer.Tools;

[McpServerToolType]
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)
    {
        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<CommandTools>();

项目架构

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

关键组件：

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

🛠️ 技术栈

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

📚 相关资源

🤝 贡献

欢迎提交 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 文件。

⚠️ 免责声明

  • 本项目当前版本为 3.6.5
  • 3.0.0 移除了 Excel 导出与数据库文档生成 tools，升级前请检查现有调用
  • 2.0.0 版本包含破坏性变更，请参考迁移指南
  • 生产环境使用前请充分测试
  • 定期备份重要数据
  • 注意配置中的敏感信息保护

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

Collected info

  • ★ 37 stars
  • ⎇ 8 forks
  • Language: C#
  • Source updated: 9/8/2026

Config for your environment

Replace {MCP_ENDPOINT_URL} with this MCP’s endpoint URL (from its repo or docs above). No API key — you connect directly.

Tool

OS

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-server": {
      "url": "{MCP_ENDPOINT_URL}"
    }
  }
}

Paste into mcpServers in the config file. Restart Cursor after saving.

If this MCP is also published on mcpchannel.ai, you can subscribe from Browse and use the gateway config there instead.