文件管理器 MCP 服务器
一个基于 Model Context Protocol (MCP) 的文件管理服务器，为 AI 助手提供安全的文件系统操作能力。
功能特性
核心工具
-
list_directory - 列出目录内容
- 显示文件和子目录
- 可选显示隐藏文件
- 显示文件大小信息
-
read_file - 读取文件内容
- 支持多种编码格式
- 文件大小限制（10MB）
- 自动检测二进制文件
-
create_file - 创建新文件
- 自动创建父目录
- 防止覆盖现有文件
- 支持自定义编码
-
delete_file - 删除文件或目录
- 安全删除确认
- 支持递归删除目录
- 权限检查
-
search_files - 搜索文件
- 支持通配符模式
- 递归搜索选项
- 显示匹配结果统计
-
copy_files - 复制文件
- 支持单个或多个文件复制
- 自动创建目标文件夹
- 可选择是否覆盖已存在文件
- 详细的操作结果报告
安全特性
- 参数验证: 严格的输入参数验证
- 路径安全: 防止路径遍历攻击
- 权限控制: 尊重文件系统权限
- 错误处理: 详细的错误信息和日志记录
- 文件大小限制: 防止处理过大文件
安装和设置
环境要求
- Python 3.8+
- pip 或 pipenv
安装步骤
-
克隆项目
git clone <repository-url> cd mcpDevelop -
创建虚拟环境
python3 -m venv venv source venv/bin/activate # Linux/Mac # 或 venv\Scripts\activate # Windows -
安装依赖
pip install -r requirements.txt
使用方法
启动服务器
# 方法1: 直接运行主文件
python main.py
# 方法2: 作为模块运行
python -m file_manager_mcp.server
在 AI 客户端中配置
将以下配置添加到你的 MCP 客户端配置文件中：
{
"mcpServers": {
"file-manager": {
"command": "python",
"args": ["/path/to/mcpDevelop/main.py"]
}
}
}
工具使用示例
1. 列出目录内容
{
"name": "list_directory",
"arguments": {
"path": "/home/user/documents",
"show_hidden": false
}
}
2. 读取文件
{
"name": "read_file",
"arguments": {
"path": "/home/user/example.txt",
"encoding": "utf-8"
}
}
3. 创建文件
{
"name": "create_file",
"arguments": {
"path": "/home/user/new_file.txt",
"content": "Hello, World!",
"encoding": "utf-8"
}
}
4. 删除文件
{
"name": "delete_file",
"arguments": {
"path": "/home/user/old_file.txt",
"recursive": false
}
}
5. 搜索文件
{
"name": "search_files",
"arguments": {
"directory": "/home/user/projects",
"pattern": "*.py",
"recursive": true
}
}
6. 复制文件
{
"name": "copy_files",
"arguments": {
"source_paths": ["/home/user/file1.txt", "/home/user/file2.txt"],
"destination_folder": "/home/user/backup",
"overwrite": false
}
}
项目结构
mcpDevelop/
├── file_manager_mcp/
│ ├── __init__.py # 包初始化
│ ├── server.py # MCP 服务器主程序
│ ├── tools.py # 工具实现
│ └── validators.py # 参数验证和错误处理
├── main.py # 入口文件
├── requirements.txt # Python 依赖
├── pyproject.toml # 项目配置
└── README.md # 项目文档
开发和测试
运行测试
# 激活虚拟环境
source venv/bin/activate
# 运行基本功能测试
python -c "import file_manager_mcp.tools; print('导入成功')"
调试模式
设置环境变量启用详细日志：
export PYTHONPATH=.
export MCP_LOG_LEVEL=DEBUG
python main.py
安全注意事项
- 文件系统访问: 此服务器可以访问运行用户权限范围内的所有文件
- 路径验证: 已实现路径遍历攻击防护
- 文件大小限制: 读取和创建文件有大小限制
- 权限检查: 尊重操作系统的文件权限设置
故障排除
常见问题
-
权限错误
- 确保运行用户有足够的文件系统权限
- 检查目标文件/目录的权限设置
-
编码错误
- 确认文件编码格式
- 尝试使用不同的编码参数
-
路径错误
- 使用绝对路径
- 确认路径存在且格式正确
日志查看
服务器会输出详细的日志信息，包括：
- 工具调用记录
- 错误信息
- 参数验证结果
贡献指南
- Fork 项目
- 创建功能分支
- 提交更改
- 推送到分支
- 创建 Pull Request
许可证
本项目采用 MIT 许可证。详见 LICENSE 文件。
更新日志
v0.1.1
- 新增 copy_files 工具
- 支持单个或多个文件复制到目标文件夹
- 增强文件操作功能覆盖范围
v0.1.0
- 初始版本
- 实现 5 个核心文件操作工具
- 添加参数验证和错误处理
- 完整的 MCP 协议支持