AI导哈

文件系统MCP服务器

一个基于Rust构建的跨平台MCP协议服务器，提供安全的沙盒化文件系统操作工具，适用于AI助手和MCP兼容应用的集成。

  • by sudhanvarao28
  • Rust
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 sudhanvarao28/filesystem-mcp

使用说明

文件系统-MCP（或“文件系统-多通道协议”，具体翻译取决于MCP在此上下文中的具体含义，MCP可能代表多种概念，如多通道协议、特定硬件/软件的名称等）

一个强大且跨平台的模型上下文协议（MCP）服务器，它将强大的文件系统操作作为MCP客户端的工具进行暴露。该服务器使用Rust语言构建，并支持异步/等待（async/await）特性，通过标准化协议实现安全的沙箱文件系统访问。

概述

文件系统-MCP 是一个MCP服务器实现，提供了五个核心文件系统工具：

  • **list_dir（在编程或命令行语境中，通常指列出目录内容的命令或函数）**列出指定路径下的文件和目录
  • 读取文件读取文件的内容
  • 写文件写入或创建一个包含指定内容的文件
  • 删除文件从文件系统中删除一个文件
  • 搜索文本在所有文件中递归搜索文本模式

所有操作均通过stdio传输协议使用MCP协议执行，这使其非常适合与AI助手、Claude插件以及其他MCP兼容的应用程序进行集成。

安装

下载预编译的二进制文件

预编译的二进制文件适用于多个平台。请访问 GitHub 发布版（或版本发布） 访问页面并下载适用于您系统的相应存档文件：

  • macOS（Intel版）: filesystem-mcp-macos-x86_64.tar.gz
  • macOS（ARM64）： filesystem-mcp-macos-arm64.tar.gz
  • Linux（x86_64架构）: filesystem-mcp-linux-x86_64.tar.xz
  • Windows（x86_64）： filesystem-mcp-windows-x86_64.zip

将存档解压到您选择的位置。二进制文件无需任何额外依赖即可使用。

从源代码构建

自己搭建服务器：

git clone https://github.com/yourusername/filesystem-mcp.git
cd filesystem-mcp
cargo build --release

编译后的二进制文件将位于 target/release/filesystem-mcp （或者 filesystem-mcp.exe （在Windows上）。

MacOS的权限

xattr -d com.apple.quarantine <filesystem-mcp binary>

配置

Claude 桌面集成

使用 文件系统-MCP 使用 Claude Desktop 时，请在您的 Claude 设置文件中添加以下配置：

macOS/Linux： ~/.config/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp",
      "args": []
    }
  }
}

替换 /path/to/filesystem-mcp 带有解压或编译后的二进制文件的绝对路径。例如：

  • macOS/Linux（注：macOS是苹果公司的操作系统，Linux是一个开源的计算机操作系统）： /Users/username/tools/filesystem-mcp 或者 /home/username/tools/filesystem-mcp
  • Windows： C:\\Users\\username\\tools\\filesystem-mcp.exe

验证

配置完成后，重启Claude桌面应用。现在，文件系统工具应该可以在您的聊天中使用了。您可以通过让Claude列出某个目录中的文件来验证其是否正常工作。

ChatGPT集成

使用 文件系统-MCP（或“多协议控制器文件系统”，具体翻译取决于MCP在此上下文中的具体含义，但通常MCP可指多种协议控制器或类似技术） 通过自定义GPT或OpenAI平台使用ChatGPT，请按照以下步骤操作：

与OpenAI的GPT自定义操作配合使用

  1. 创建或编辑您的GPT首选 ChatGPT平台 并创建一个新的GPT或编辑现有的一个。

  2. 导航至自定义操作在GPT配置中，转到“操作”选项卡并选择“创建新操作”。

  3. 配置操作您无需使用HTTP操作，而是需要通过您的本地环境来连接MCP服务器。ChatGPT不直接支持MCP服务器，因此您有几种选择：

选项A：使用HTTP桥接（推荐）

在文件系统-mcp服务器周围创建一个简单的HTTP封装器：

# You can use a tool like socat or create a custom Node.js bridge
socat TCP-LISTEN:3000,reuseaddr EXEC:"/path/to/filesystem-mcp"

然后配置你的ChatGPT自定义操作以调用 http://localhost:3000/ 使用适当的有效载荷格式。

选项B：通过VSCode扩展使用

如果你正在使用支持MCP的VSCode扩展：

  1. 为VSCode安装一个MCP扩展
  2. 在您的VSCode设置中进行配置：
{
  "mcp.servers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp",
      "args": []
    }
  }
}
  1. 在VSCode的AI助手功能中直接使用文件系统工具

选项C：与Cursor IDE一起使用

如果你正在使用 Cursor IDE（它原生支持 MCP）：

  1. 打开光标设置（在 macOS 上按 Cmd+, 或在 Windows/Linux 上按 Ctrl+,）
  2. 转到“功能”选项卡并找到“MCP 服务器”
  3. 添加配置：
{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp",
      "args": []
    }
  }
}
  1. 重启光标后，文件系统工具将可供AI助手使用

选项D：与第三方MCP客户端一起使用

多个第三方应用程序支持MCP服务器：

  • MCP 检查器一个能够连接到您MCP服务器的调试工具
  • 自定义集成脚本编写你自己的客户端，通过标准输入输出连接到MCP服务器

ChatGPT的局限性

目前，ChatGPT并不像Claude Desktop那样原生支持MCP（可能是指某种特定的插件或功能模块）。建议的方法是使用 Claude 桌面版 或者 Cursor 集成开发环境（IDE） 为了获得最佳的filesystem-mcp体验，如果您需要集成ChatGPT，请考虑使用选项A中描述的HTTP桥接方式。

可用工具

list_dir（在编程或命令行中，通常表示列出目录内容的命令或函数）

列出指定路径下的所有文件和目录。

输入：

  • path目录路径（相对于当前工作目录）

输出：

  • 文件/目录名称的JSON数组
  • 显示已解析完整路径的调试信息

读取文件

读取并返回文件的全部内容。

输入：

  • path文件路径（相对于当前工作目录）

输出：

  • 将文件内容完整显示为文本

写文件

创建一个新文件或用提供的内容覆盖现有文件。

输入：

  • path文件路径（相对于当前工作目录）
  • content要写入文件的文本内容

输出：

  • 成功确认信息

删除文件

从文件系统中删除一个文件。

输入：

  • path文件路径（相对于当前工作目录）

输出：

  • 成功确认信息

搜索文本

递归地搜索当前目录树中的所有文件，查找包含特定文本模式的文件。

输入：

  • query要搜索的文本字符串

输出：

  • 包含匹配项的文件路径的JSON数组
  • 统计摘要（已处理文件数、跳过文件数、找到匹配项数）

建筑学

该服务器基于MCP服务器框架构建，并实现了以下组件：

**FsToolbox（src/filesystem.rs）**该核心处理程序使用Rust的标准库以及（其他相关库，此处原文未完整）来实现所有文件系统操作 walkdir 用于高效目录遍历的框架/工具。

**主服务器（src/main.rs）**初始化FsToolbox并通过stdio传输方式使其可用，从而使其与MCP客户端兼容。

依赖项：

  • rmcp (0.8.1): 使用stdio传输的MCP协议实现
  • tokio (1.47.1): 用于处理并发操作的异步运行时
  • serde/serde_json工具参数的JSON序列化
  • schemars工具定义的JSON Schema生成
  • walkdir高效的递归目录遍历
  • anyhow错误处理

安全考虑因素

  • 所有文件路径均相对于服务器启动时的当前工作目录进行解析
  • 服务器在操作前验证路径是否存在以及是否可访问
  • 底层实现并未强制限制超出基础目录的路径遍历
  • 在搜索操作过程中遇到的文件读取错误会被妥善处理，而不会导致整个搜索失败

使用示例

使用 Claude Desktop

配置完成后，您可以在对话中自然地使用文件系统工具：

User: "List the files in my current directory"
Claude: [Uses list_dir tool]

User: "Read the contents of config.json"
Claude: [Uses read_file tool]

User: "Create a new file called notes.txt with the following content..."
Claude: [Uses write_file tool]

User: "Search for all files containing 'TODO' comments"
Claude: [Uses search_text tool to find matches]

使用 Cursor 集成开发环境 (IDE)

User: "Can you list all Python files in this project?"
Cursor AI: [Uses list_dir and search_text tools to find .py files]

User: "Read my project configuration"
Cursor AI: [Uses read_file to fetch config files]

发展

构建开发二进制文件

对于开发阶段，你可以不启用发布优化来进行构建：

cargo build
./target/debug/filesystem-mcp

调试

服务器将详细的日志信息输出到标准错误流（stderr），这有助于诊断问题：

[FsToolbox] Initialized with base_path: "."
[list_dir] Requested path: "."
[list_dir] Full path: "."
[list_dir] Found 5 entries

在运行 Claude Desktop 时，要查看这些日志，请检查 Claude 应用程序的日志。

发行说明

这个项目使用GitHub Actions进行跨平台的自动化构建和发布。当创建新版本时：

  1. 该工作流为所有支持的平台构建二进制文件：

    • x86_64 Linux（GNU）
    • x86_64 Windows（MSVC）
    • x86_64 macOS（Darwin）
    • ARM64 macOS（Apple Silicon）

  2. 每个二进制文件都以平台特定的格式进行存档：

    • .tar.xz 适用于Linux
    • .zip 适用于Windows
    • .tar.gz 适用于 macOS

  3. 所有存档都已上传至GitHub发布页面以供下载

故障排除

“命令未找到”错误

确保配置文件中的路径是绝对路径（以 / 在 macOS/Linux 上或 C:\ （在Windows上）并指向一个现有的可执行文件。

在 macOS/Linux 上权限被拒绝

该二进制文件可能需要可执行权限。运行：

chmod +x /path/to/filesystem-mcp

文件操作失败

检查当前工作目录是否设置正确，并且具有执行所需操作的适当权限。

MCP服务器无法连接

如果服务器无法连接：

  1. 验证二进制路径是否正确且文件是否可执行
  2. 直接在终端测试该二进制文件以确保其能运行
  3. 检查应用程序日志以获取详细的错误信息
  4. 确保二进制文件所在位置没有权限问题

贡献

欢迎贡献！请随时提交问题和拉取请求。

许可证

此项目采用MIT许可证授权。

支持

如需报告问题、提出疑问或功能请求，请在GitHub仓库上提交一个问题。

相关 MCP