MCP Database Filesystem
English | 中文
一个简洁高效的 MCP (Model Context Protocol) 服务器，提供多数据库访问和文件系统操作功能。
✨ 主要特性
🗄️ 多数据库支持
SQL Server
- SQL 查询执行 - 支持 SELECT 查询
- SQL 命令执行 - 支持 INSERT/UPDATE/DELETE 操作
- 表结构查询 - 获取表的详细结构信息和字段描述
- 表列表 - 列出数据库中的所有表
MySQL
- MySQL 查询执行 - 支持 MySQL SELECT 查询
- MySQL 命令执行 - 支持 INSERT/UPDATE/DELETE 操作
- MySQL 表结构查询 - 获取 MySQL 表的详细结构信息
- MySQL 表列表 - 列出 MySQL 数据库中的所有表
Redis
- 键值操作 - GET/SET/DELETE 键值对
- 键管理 - 列出匹配模式的键
- 服务器信息 - 获取 Redis 服务器状态信息
- 过期设置 - 支持键的过期时间设置
📁 文件系统功能
- 文件读取 - 读取文件内容
- 文件写入 - 写入内容到文件
- 目录列表 - 列出目录内容
🔒 安全特性
- SQL 注入防护
- 文件系统访问控制
- 环境变量配置
- 权限验证
🔄 容错机制
- 优雅降级 - 任何数据库连接失败时不影响其他服务
- 动态重连 - 支持运行时重新连接各种数据库
- 状态监控 - 实时监控所有数据库连接状态
🚀 快速开始
📋 前置要求
根据您要使用的数据库服务，安装相应的驱动程序：
1. SQL Server (可选)
安装 ODBC Driver for SQL Server
Windows:
# 下载并安装 Microsoft ODBC Driver 17 for SQL Server
# 访问: https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
# 或使用 winget 安装
winget install Microsoft.ODBCDriverforSQLServer
macOS:
# 使用 Homebrew 安装
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql17 mssql-tools
Linux (Ubuntu/Debian):
# 添加 Microsoft 仓库
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
# 安装驱动
sudo apt-get update
sudo apt-get install msodbcsql17
2. 验证 ODBC 安装
# Windows
odbcad32.exe
# macOS/Linux
odbcinst -j
2. MySQL (可选)
如果要使用 MySQL 功能，确保 MySQL 服务器可访问。不需要额外的客户端驱动，PyMySQL 已包含在依赖中。
3. Redis (可选)
如果要使用 Redis 功能，确保 Redis 服务器可访问。不需要额外的客户端驱动，redis-py 已包含在依赖中。
📦 零安装使用（推荐）
# 安装 uv（如果尚未安装）
pip install uv
# 直接运行 - 无需克隆仓库！
uvx mcp-db-filesystem@latest
🔧 配置
在你的 MCP 客户端（如 Claude Desktop、AugmentCode）中添加以下配置：
{
"mcpServers": {
"mcp-db-filesystem": {
"command": "uvx",
"args": ["mcp-db-filesystem@latest"],
"env": {
// SQL Server Configuration (可选)
"MSSQL_SERVER": "localhost",
"MSSQL_DATABASE": "your_database",
"MSSQL_USERNAME": "your_username",
"MSSQL_PASSWORD": "your_password",
"MSSQL_USE_WINDOWS_AUTH": "true",
"MSSQL_PORT": "1433",
"MSSQL_DRIVER": "ODBC Driver 17 for SQL Server",
"MSSQL_CONNECTION_TIMEOUT": "30",
"MSSQL_COMMAND_TIMEOUT": "30",
"MSSQL_POOL_SIZE": "5",
"MSSQL_MAX_OVERFLOW": "10",
"MSSQL_TRUST_SERVER_CERTIFICATE": "true",
"MSSQL_ENCRYPT": "false",
"MSSQL_MULTIPLE_ACTIVE_RESULT_SETS": "true",
"MSSQL_APPLICATION_NAME": "MCP-Db-Filesystem",
// MySQL Configuration (可选)
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_DATABASE": "your_mysql_database",
"MYSQL_USERNAME": "your_mysql_username",
"MYSQL_PASSWORD": "your_mysql_password",
"MYSQL_CHARSET": "utf8mb4",
"MYSQL_CONNECTION_TIMEOUT": "30",
"MYSQL_POOL_SIZE": "5",
"MYSQL_MAX_OVERFLOW": "10",
// Redis Configuration (可选)
"REDIS_HOST": "localhost",
"REDIS_PORT": "6379",
"REDIS_DB": "0",
"REDIS_PASSWORD": "your_redis_password",
"REDIS_SOCKET_TIMEOUT": "30",
"REDIS_CONNECTION_TIMEOUT": "30",
"REDIS_MAX_CONNECTIONS": "10",
// Filesystem Configuration
"FS_ALLOWED_PATHS": "*",
"FS_ALLOWED_EXTENSIONS": "*.*",
"FS_MAX_FILE_SIZE": "1073741824",
"FS_ENABLE_WRITE": "true",
"FS_ENABLE_DELETE": "true",
"FS_IGNORE_FILE_LOCKS": "false",
// Security Configuration
"SECURITY_ENABLE_SQL_INJECTION_PROTECTION": "true",
"SECURITY_MAX_QUERY_LENGTH": "10000",
"SECURITY_ENABLE_QUERY_LOGGING": "true",
"SECURITY_LOG_SENSITIVE_DATA": "false",
// Server Configuration
"SERVER_LOG_LEVEL": "INFO",
"SERVER_DEBUG": "false"
}
}
}
}
🛠️ 可用工具
SQL Server 工具
sql_query- 执行 SQL Server SELECT 查询sql_execute- 执行 SQL Server INSERT/UPDATE/DELETE 命令list_tables- 列出 SQL Server 数据库中的所有表get_table_schema- 获取 SQL Server 表的结构信息database_reconnect- 重新连接 SQL Server
MySQL 工具
mysql_query- 执行 MySQL SELECT 查询mysql_execute- 执行 MySQL INSERT/UPDATE/DELETE 命令mysql_list_tables- 列出 MySQL 数据库中的所有表mysql_get_table_schema- 获取 MySQL 表的结构信息mysql_reconnect- 重新连接 MySQL
Redis 工具
redis_get- 获取 Redis 键值redis_set- 设置 Redis 键值（支持过期时间）redis_delete- 删除 Redis 键redis_keys- 列出匹配模式的 Redis 键redis_info- 获取 Redis 服务器信息redis_reconnect- 重新连接 Redis
数据库管理工具
database_status- 检查所有数据库连接状态
文件系统工具
read_file- 读取文件内容write_file- 写入文件内容list_directory- 列出目录内容delete_file- 删除文件（需要确认）create_directory- 创建目录delete_file- 删除文件（需要确认）create_directory- 创建目录
📋 环境变量
SQL Server 配置
MSSQL_SERVER- SQL Server 服务器地址MSSQL_DATABASE- 数据库名称MSSQL_USERNAME- 用户名MSSQL_PASSWORD- 密码MSSQL_USE_WINDOWS_AUTH- 是否使用 Windows 身份验证MSSQL_PORT- SQL Server 端口（默认 1433）MSSQL_DRIVER- ODBC 驱动名称MSSQL_CONNECTION_TIMEOUT- 连接超时时间（秒）MSSQL_COMMAND_TIMEOUT- 命令超时时间（秒）MSSQL_POOL_SIZE- 连接池大小MSSQL_MAX_OVERFLOW- 最大溢出连接数MSSQL_TRUST_SERVER_CERTIFICATE- 是否信任服务器证书MSSQL_ENCRYPT- 是否加密连接MSSQL_MULTIPLE_ACTIVE_RESULT_SETS- 是否启用多活动结果集MSSQL_APPLICATION_NAME- 应用程序名称
MySQL 配置
MYSQL_HOST- MySQL 服务器地址MYSQL_PORT- MySQL 端口（默认 3306）MYSQL_DATABASE- MySQL 数据库名称MYSQL_USERNAME- MySQL 用户名MYSQL_PASSWORD- MySQL 密码MYSQL_CHARSET- 字符集（默认 utf8mb4）MYSQL_CONNECTION_TIMEOUT- 连接超时时间（秒）MYSQL_POOL_SIZE- 连接池大小MYSQL_MAX_OVERFLOW- 最大溢出连接数
Redis 配置
REDIS_HOST- Redis 服务器地址REDIS_PORT- Redis 端口（默认 6379）REDIS_DB- Redis 数据库编号（默认 0）REDIS_PASSWORD- Redis 密码（可选）REDIS_SOCKET_TIMEOUT- Socket 超时时间（秒）REDIS_CONNECTION_TIMEOUT- 连接超时时间（秒）REDIS_MAX_CONNECTIONS- 最大连接数
文件系统配置
FS_ALLOWED_PATHS- 允许访问的路径（*表示所有路径）FS_ALLOWED_EXTENSIONS- 允许的文件扩展名（*.*表示所有文件）FS_MAX_FILE_SIZE- 最大文件大小（字节）FS_ENABLE_WRITE- 是否启用写操作FS_ENABLE_DELETE- 是否启用删除操作FS_IGNORE_FILE_LOCKS- 是否忽略文件锁
🔧 开发
本地开发
# 克隆仓库
git clone https://github.com/ppengit/mcp-db-filesystem.git
cd mcp-db-filesystem
# 安装依赖
uv sync
# 运行服务器
uv run python -m mcp_db_filesystem server
测试
# 运行测试
uv run pytest
# 运行特定测试
uv run pytest tests/test_database.py
📄 许可证
MIT License - 详见 LICENSE 文件。
🤝 贡献
欢迎贡献！请提交 Issue 或 Pull Request。
❓ 常见问题
Q: 出现 "No module named 'pyodbc'" 错误
A: 请确保已安装 ODBC Driver for SQL Server，参见上面的前置要求部分。
Q: 出现 "Data source name not found" 错误
A: 检查 DB_SERVER 配置是否正确，确保 SQL Server 服务正在运行。
Q: 连接超时或拒绝连接
A:
- 检查 SQL Server 是否启用了 TCP/IP 协议
- 确认防火墙设置允许连接到 SQL Server 端口（默认1433）
- 验证用户名和密码是否正确
Q: 文件系统操作被拒绝
A: 检查 FS_ALLOWED_PATHS 和 FS_ALLOWED_EXTENSIONS 配置，确保路径和文件类型被允许访问。
📞 支持
- GitHub Issues: https://github.com/ppengit/mcp-db-filesystem/issues
🔄 更新日志
v1.0.1
- 🎉 首个稳定版本发布
- ✨ 完整的 SQL Server 数据库支持
- 📁 全面的文件系统操作
- 🔒 增强的安全特性
- 📝 改进的错误处理和日志记录
- 🚀 简化的架构，专注于核心功能
注意: 此版本专注于核心功能的稳定性和可靠性，提供简洁高效的MCP服务器体验。