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: 连接超时或拒绝连接

检查 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服务器体验。

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables SQL Server database operations (queries, table management) and file system access (read, write, directory listing) with security controls. Supports comprehensive database interactions and file management through a unified MCP interface.

Related MCP Servers

MSSQL MCP Server
c0h1b4
A
security
A
license
A
quality
Enables execution of SQL queries and management of Microsoft SQL Server database connections through the Model Context Protocol.
Last updated -
33
56
14
MIT License
SQL Server Express MCP Server
hanweg
-
security
A
license
-
quality
Facilitates interaction with Microsoft SQL Server Express, supporting database operations such as querying, table management, and schema inspection via natural language MCP commands.
Last updated -
4
MIT License
Jewei MSSQL MCP Server
jeweis
-
security
A
license
-
quality
A FastMCP-based server that enables executing Microsoft SQL Server data queries and table structure queries through a standardized MCP protocol interface.
Last updated -
3
MIT License
MSSQL MCP Server
NakiriYuuzu
A
security
A
license
A
quality
Enables interaction with Microsoft SQL Server databases through a Model Context Protocol interface, supporting database connections, switching between databases, and executing secure SELECT queries.
Last updated -
8
151
MIT License

View all related MCP servers