AI导哈

文件系统服务器

一个为Claude Desktop提供安全文件和目录操作的MCP服务器，具有路径限制、文件大小限制和权限处理等安全特性。

  • by nandarizkika
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 nandarizkika/mcp-filesystem-server

使用说明

MCP文件系统服务器

一种模型上下文协议（MCP）服务器，为Claude Desktop提供安全的文件和目录操作。

特性

  • 📁 列出目录内容及详细信息
  • 📄 安全读取文本文件（有大小限制）
  • ✏️ 将内容写入文件
  • 🗂️ 创建目录
  • 🗑️ 删除文件和目录
  • 🔍 获取详细的文件/目录信息
  • 🔐 具有路径限制的内置安全性

安全功能

  • ✅ 路径限制：只允许访问安全的预定义目录
  • ✅ 文件大小限制：不会读取大于1MB的文件以防止内存问题
  • ✅ 权限处理：优雅地处理拒绝权限的错误
  • ✅ 路径验证：防止目录遍历攻击
  • ✅ 安全操作：所有文件操作在执行前都经过验证

可用工具

list_directory

列出目录的内容，包括文件大小、类型和修改日期。

参数：

  • path （必需）：列表的目录路径

例子： “列出我的文档文件夹的内容”

read_file

读取文本文件的内容（最大1MB）。

参数：

  • path （必填）：要读取的文件路径

例子： “阅读D:\Projects\README.md中的文件”

write_file

将内容写入文件，必要时创建目录。

参数：

  • path （必填）：要写入的文件路径
  • content （必填）：要写的内容

例子： “将'Hello World'写入我的文档中名为Hello.txt的文件”

create_directory

创建一个新目录，包括父目录（如果需要）。

参数：

  • path （必需）：要创建的目录路径

例子： “在我的文档中创建一个名为“项目”的新目录”

delete_file

删除文件或目录（包括所有内容）。

参数：

  • path （必填）：删除路径

例子： “删除我的文档中的旧test.txt文件”

get_file_info

获取有关文件或目录的详细信息。

参数：

  • path （必填）：获取有关信息的路径

例子： “获取有关我的下载文件夹的信息”

先决条件

  • Python 3.7+
  • Claude桌面应用程序
  • MCP Python包

安装

  1. 克隆存储库：

    git clone https://github.com/nandarizkika/mcp-filesystem-server.git
cd mcp-filesystem-server

  2. 创建虚拟环境：

    python -m venv .venv
.venv\Scripts\activate  # On Windows
# or
source .venv/bin/activate  # On macOS/Linux

  3. 安装依赖项：

    pip install -r requirements.txt

配置

默认允许的目录

默认情况下，服务器限制对这些安全目录的访问：

  • 用户主目录和子目录
  • 文档、桌面、下载文件夹
  • 自定义项目目录（可配置）

自定义目录配置

您可以在中修改允许的目录 MCPFilesystemServer 构造函数：

# Example: Add custom allowed directories
server = MCPFilesystemServer(allowed_directories=[
    "C:\\Users\\YourName\\Documents",
    "C:\\Users\\YourName\\Desktop",
    "C:\\Users\\YourName\\Downloads",
    "D:\\YourProjectFolder",
    # Add more as needed
])

Claude桌面设置

  1. 找到您的Claude Desktop配置文件：

    • 窗户： %APPDATA%\Claude\claude_desktop_config.json
    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json

  2. 添加文件系统服务器配置：

    {
  "mcpServers": {
    "filesystem": {
      "command": "path/to/your/project/.venv/Scripts/python.exe",
      "args": ["path/to/your/project/filesystem_server.py"]
    }
  }
}

  3. 重新启动克劳德桌面

测试

独立测试服务器：

python test_filesystem.py

使用示例

一旦配置了Claude Desktop，您就可以问自然语言问题：

目录操作

  • “列出我的文档文件夹的内容”
  • “显示下载目录中的内容”
  • “我的项目文件夹中有哪些文件？”

文件读取

  • “阅读D:\Projects\README.md中的文件”
  • “显示config.txt文件的内容”
  • “我的notes.txt文件中有什么？”

文件写入

  • “将'Hello World'写入我的文档中名为Hello.txt的文件”
  • “用我的项目想法创建一个名为notes.txt的新文件”
  • “将我的会议笔记保存到桌面中的文件”

目录管理

  • “在我的文档中创建一个名为'backup'的新目录”
  • 在我的主目录中创建一个名为“projects”的新文件夹
  • “为我的新项目创建目录结构”

文件信息

  • “获取有关我的下载文件夹的信息”
  • “显示项目目录的大小和详细信息”
  • “我的README.md文件上次修改是什么时候？”

文件清理

  • “删除我的文档中的旧test.txt文件”
  • “删除我创建的临时目录”
  • “清理旧备份文件”

项目结构

mcp-filesystem-server/
├── filesystem_server.py       # Main MCP server
├── test_filesystem.py         # Test script
├── requirements.txt           # Python dependencies
├── .gitignore                # Git ignore rules
├── LICENSE                   # MIT License
└── README.md                # This file

安全考虑

路径限制

  • 只有预定义的目录是可访问的
  • 无法访问系统目录（C:\Windows、/etc等）
  • 无法访问其他用户的目录
  • 路径遍历尝试被阻止

文件大小限制

  • 文本文件限制为1MB，以防止内存问题
  • 二进制文件被拒绝进行读取操作
  • 高效处理大型目录列表

权限处理

  • 权限拒绝错误得到妥善处理
  • 未暴露敏感错误信息
  • 操作安全失败，不会崩溃

故障排除

常见问题

  1. “拒绝访问”错误：

    • 检查路径是否在允许的目录列表中
    • 验证您对该目录具有适当的权限
    • 确保路径存在且可访问

  2. Claude中的“服务器已断开连接”：

    • 检查配置中的文件路径是否正确
    • 确保Python可执行路径准确
    • 配置更改后重新启动Claude Desktop

  3. “文件太大”错误：

    • 为了安全起见，服务器将文本文件限制为1MB
    • 使用外部工具处理较大的文件
    • 考虑分块处理文件

调试步骤

  1. 独立测试服务器：

    python test_filesystem.py

  2. 在Claude Desktop中检查服务器日志

  3. 验证系统上的文件权限

  4. 先用简单的操作进行测试

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关项目

致谢

  • Anthropic 用于Claude和MCP规范
  • MCP社区，用于协议文档和示例
  • 提供反馈和改进的贡献者和用户

⚠️ 重要：此服务器提供文件系统访问。在生产环境中使用之前，始终审查并了解安全影响。

由以下材料制成❤️ 对于MCP社区

相关 MCP