文件系统MCP服务器
Node.js服务器实现了用于文件系统操作的模型上下文协议（MCP）。
特性
- 读/写文件
- 创建/列出/删除目录
- 移动文件/目录
- 搜索文件
- 获取文件元数据
- 通过动态目录访问控制 根
目录访问控制
服务器使用灵活的目录访问控制系统。目录可以通过命令行参数指定，也可以通过以下方式动态指定 根.
方法1：命令行参数
启动服务器时指定允许的目录：
mcp-server-filesystem /path/to/dir1 /path/to/dir2方法2:MCP根（推荐）
支持的MCP客户端 根 可以动态更新Allowed目录。
客户端通知服务器的根目录，在提供时完全替换任何服务器端允许的目录。
重要：如果服务器在没有命令行参数的情况下启动，并且客户端不支持根协议（或提供空根），则服务器将在初始化过程中抛出错误。
这是推荐的方法，因为这可以通过以下方式实现运行时目录更新 roots/list_changed 无需重新启动服务器即可发出通知，提供更灵活、更现代的集成体验。
运作原理
服务器的目录访问控制遵循以下流程：
- 服务器启动
- 服务器从命令行参数（如果提供）中的目录开始 - 如果没有提供参数，服务器将从允许的空目录开始
- 客户端连接和初始化
- 客户端连接并发送 initialize 具有能力的请求 - 服务器检查客户端是否支持根协议(capabilities.roots)
- 根协议处理 （如果客户端支持root）
- 初始化时：服务器通过从客户端请求根 roots/list - 客户端使用其配置的根进行响应 - 服务器将所有允许的目录替换为客户端的根目录 - 运行时更新：客户端可以发送 notifications/roots/list_changed - 服务器请求更新根目录并再次替换允许的目录
- 回退行为 （如果客户端不支持根）
- 服务器仅继续使用命令行目录 - 无法进行动态更新
- 访问控制
- 所有文件系统操作都限制在允许的目录中 - 使用 list_allowed_directories 查看当前目录的工具 - 服务器需要至少一个允许的目录才能运行
备注：服务器只允许在通过以下方式指定的目录内进行操作 args 或者通过Roots。
API
工具
- read_text_file
- 以文本形式读取文件的完整内容 - 输入： - path （字符串） - head （数字，可选）：前N行 - tail （数字，可选）：最后N行 - 始终将文件视为UTF-8文本，而不管扩展名如何 - 不能同时指定 head 和 tail 同时
- read_media_file
- 读取图像或音频文件 - 输入： - path （字符串） - 流式传输文件并返回具有相应MIME类型的base64数据
- 读取多个文件
- 同时读取多个文件 - 输入： paths （字符串\[\]） - 读取失败不会停止整个操作
- write_file
- 创建新文件或覆盖现有文件（请谨慎操作） - 输入： - path （string）：文件位置 - content （string）：文件内容
- edit_file
- 使用高级模式匹配和格式进行选择性编辑 - 特征： - 基于行和多行内容匹配 - 保留缩进的空白归一化 - 具有正确定位的多个同时编辑 - 压痕样式检测和保存 - 带上下文的Git风格差异输出 - 使用模拟运行模式预览更改 - 输入： - path （string）：要编辑的文件 - edits （array）：编辑操作列表 - oldText （string）：要搜索的文本（可以是子字符串） - newText （string）：要替换的文本 - dryRun （boolean）：预览更改而不应用（默认值：false） - 返回模拟运行的详细差异和匹配信息，否则应用更改 - 最佳实践：在应用更改之前，始终先使用dryRun预览更改
- create_directory
- 创建新目录或确保其存在 - 输入： path （字符串） - 如果需要，创建父目录 - 如果目录存在，则自动成功
- list_directory
- 列出带有\[FILE\]或\[DIR\]前缀的目录内容 - 输入： path （字符串）
- list_directory_with_sizes
- 列出带有\[FILE\]或\[DIR\]前缀的目录内容，包括文件大小 - 输入： - path （string）：列表的目录路径 - sortBy （字符串，可选）：按“名称”或“大小”对条目进行排序（默认值：“名称”） - 返回包含文件大小和摘要统计信息的详细列表 - 显示总文件、目录和组合大小
- move_file
- 移动或重命名文件和目录 - 输入： - source （字符串） - destination （字符串） - 如果目标存在，则失败
- 搜索文件
- 递归搜索匹配或不匹配模式的文件/目录 - 输入： - path （string）：起始目录 - pattern （string）：搜索模式 - excludePatterns （string\[\]）：排除任何模式。 - 环球风格图案搭配 - 返回匹配项的完整路径
- 目录树
- 获取目录内容的递归JSON树结构 - 输入： - path （string）：起始目录 - excludePatterns （string\[\]）：排除任何模式。支持Glob格式。 - 退货： - JSON数组，其中每个条目包含： - name （string）：文件/目录名 - type （“文件”|“目录”）：条目类型 - children （array）：仅适用于目录 - 空目录的空数组 - 文件省略 - 为了提高可读性，输出采用2空格缩进格式
- 获取_文件_信息
- 获取详细的文件/目录元数据 - 输入： path （字符串） - 退货： - 尺寸 - 创建时间 - 修改时间 - 访问时间 - 类型（文件/目录） - 权限
- list_allowed_directories
- 列出服务器允许访问的所有目录 - 无需输入 - 退货： - 此服务器可以读取/写入的目录
使用Claude Desktop
将此添加到您的 claude_desktop_config.json:
注意：您可以通过将沙盒目录挂载到以下位置来向服务器提供沙盒目录 /projects.添加 ro 标志将使目录对服务器只读。
码头工人
注意：所有目录都必须挂载到 /projects 默认情况下。
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
"--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
"mcp/filesystem",
"/projects"
]
}
}
}NPX
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}使用VS代码
要快速安装，请单击下面的安装按钮。..
](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D) ](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D&quality=insiders)
对于手动安装，您可以使用以下方法之一配置MCP服务器：
方法1：用户配置（推荐） 将配置添加到用户级MCP配置文件中。打开命令选项板(Ctrl + Shift + P)然后跑 MCP: Open User Configuration。这将打开您的用户 mcp.json 您可以在其中添加服务器配置的文件。
方法2：工作空间配置 或者，您可以将配置添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。
有关VS Code中MCP配置的更多详细信息，请参阅 官方VS Code MCP文档.
您可以通过将沙盒目录挂载到以下位置来向服务器提供沙盒目录 /projects.添加 ro 标志将使目录对服务器只读。
码头工人
注意：所有目录都必须挂载到 /projects 默认情况下。
{
"servers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
"mcp/filesystem",
"/projects"
]
}
}
}NPX
{
"servers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}构建
Docker构建：
docker build -t mcp/filesystem -f src/filesystem/Dockerfile .许可证
此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。