只读文件系统MCP服务器
Node.js服务器实现了用于只读文件系统操作的模型上下文协议（MCP）。
特性
- 读取文件（文本、媒体、多个文件）
- 列出目录和目录树
- 列出目录及其大小和摘要
- 搜索文件
- 获取文件元数据
- 通过动态目录访问控制 根
目录访问控制
服务器使用灵活的目录访问控制系统。目录可以通过命令行参数指定，也可以通过以下方式动态指定 根.
方法1：命令行参数
启动服务器时指定允许的目录：
filesystem-readonly-mcp /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 （字符串\[\]） - 读取失败不会停止整个操作
- list_directory
- 列出带有\[FILE\]或\[DIR\]前缀的目录内容 - 输入： path （字符串）
- list_directory_with_sizes
- 列出目录内容，包括大小和摘要 - 输入： - path （字符串） - sortBy （“name”|“size”，可选，默认值：“name”） - 输出包括用\[FILE\]/\[DIR\]格式化的条目和文件大小
- 目录树
- 以JSON格式获取文件和目录的递归树视图 - 输入： path （字符串） - 输出：条目数组 name, type （文件|目录），以及 children 对于目录
- 搜索文件
- 递归搜索文件/目录 - 输入： - path （string）：起始目录 - pattern （string）：搜索模式 - excludePatterns （string\[\]）：排除任何模式。支持Glob格式。 - 不区分大小写的匹配 - 返回匹配项的完整路径
- 获取_文件_信息
- 获取详细的文件/目录元数据 - 输入： path （字符串） - 退货： - 尺寸 - 创建时间 - 修改时间 - 访问时间 - 类型（文件/目录） - 权限
- list_allowed_directories
- 列出服务器允许访问的所有目录 - 无需输入 - 退货： - 此服务器可以读取的目录
使用Claude Desktop
将此添加到您的 claude_desktop_config.json:
NPX
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"filesystem-readonly-mcp",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}使用VS代码
方法1：用户配置（推荐） 将配置添加到用户级MCP配置文件中。打开命令选项板(Ctrl + Shift + P)然后跑 MCP: Open User Configuration。这将打开您的用户 mcp.json 您可以在其中添加服务器配置的文件。
方法2：工作空间配置 或者，您可以将配置添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。
有关VS Code中MCP配置的更多详细信息，请参阅 官方VS Code MCP文档.
NPX
{
"servers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"filesystem-readonly-mcp",
"${workspaceFolder}"
]
}
}
}许可证
此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。