文件管理器 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 协议支持

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

File Manager MCP Server