# MCP文件系统
## 基本信息
- Slug: `rawr-ai-mcp-filesystem`
- Source: modelscope
- Publisher: @rawr-ai/mcp-filesystem
- Categories: file-systems / developer-tools / code-execution
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@rawr-ai/mcp-filesystem
## 简介
实现模型上下文协议（MCP）的 Node.js 服务器，用于文件系统操作，具有全面的权限控制，允许通过细粒度访问限制进行安全的文件和目录操作。
## MCP Server 详情

# 文件系统 MCP 服务器

Node.js 服务器实现模型上下文协议 (MCP)，用于文件系统操作，具有全面的权限控制和增强功能。

## 特性

- 细粒度的权限控制（只读、完全访问或特定操作权限）
- 在允许的目录内进行安全的文件操作
- 文件操作：
  - 读取/写入/修改文件
  - 创建/列出/删除目录
  - 移动文件/目录
  - 按名称或扩展名搜索文件
  - 获取文件元数据
- 目录操作：
  - 目录结构的树形视图
  - 带有排除模式的递归操作
- 实用函数：
  - XML 到 JSON 的转换
  - 单次调用中的多个文件操作
  - 使用模式匹配的高级文件编辑
- 安全特性：
  - 符号链接控制
  - 路径验证
  - 沙箱操作

**注意**：服务器仅允许在通过 `args` 指定的目录内，并根据配置的权限执行操作。

## API

### 资源

- `file://system`: 文件系统操作接口

### 工具

- **read_file**
  - 读取文件的完整内容
  - 输入: `path` (字符串)
  - 以 UTF-8 编码读取整个文件的内容

- **read_multiple_files**
  - 同时读取多个文件
  - 输入: `paths` (字符串数组)
  - 失败的读取不会停止整个操作

- **create_file**
  - 创建带有内容的新文件
  - 输入:
    - `path` (字符串): 文件位置
    - `content` (字符串): 文件内容
  - 如果文件已存在则失败
  - 需要 `create` 权限

- **modify_file**
  - 用新内容修改现有文件
  - 输入:
    - `path` (字符串): 文件位置
    - `content` (字符串): 新文件内容
  - 如果文件不存在则失败
  - 需要 `edit` 权限

- **edit_file**
  - 使用模式匹配和格式化进行选择性编辑
  - 功能:
    - 基于行和多行内容匹配
    - 保留缩进的空白字符规范化
    - 正确定位的多次同时编辑
    - 识别并保留缩进风格
    - 具有上下文的 Git 风格差异输出
    - 通过预览模式查看更改而不应用
  - 输入:
    - `path` (字符串): 要编辑的文件
    - `edits` (数组): 编辑操作列表
      - `oldText` (字符串): 要查找的文本（精确匹配）
      - `newText` (字符串): 要替换为的文本
    - `dryRun` (布尔值): 预览更改而不应用（默认: false）
  - 返回详细的差异信息用于预览，否则应用更改
  - 需要 `edit` 权限
  - 最佳实践: 总是先使用 dryRun 预览更改

- **create_directory**
  - 创建新目录或确保其存在
  - 输入: `path` (字符串)
  - 如需要则创建父目录
  - 如果目录已存在则静默成功
  - 需要 `create` 权限

- **list_directory**
  - 列出目录内容，带有 [FILE] 或 [DIR] 前缀
  - 输入: `path` (字符串)
  - 返回文件和目录的详细列表

- **directory_tree**
  - 获取目录结构的递归树形视图
  - 输入: `path` (字符串)
  - 返回包含文件和目录的 JSON 结构
  - 每个条目包括名称、类型和子项（对于目录）

- **move_file**
  - 移动或重命名文件和目录
  - 输入:
    - `source` (字符串): 源路径
    - `destination` (字符串): 目标路径
  - 如果目标存在则失败
  - 适用于文件和目录
  - 需要 `move` 权限

- **delete_file**
  - 删除一个文件
  - 输入: `path` (字符串)
  - 如果文件不存在则失败
  - 需要 `delete` 权限

- **delete_directory**
  - 删除一个目录
  - 输入:
    - `path` (字符串): 要删除的目录
    - `recursive` (布尔值): 是否删除内容（默认: false）
  - 如果目录不为空且 recursive 为 false 则失败
  - 需要 `delete` 权限

- **search_files**
  - 递归搜索文件/目录
  - 输入:
    - `path` (字符串): 起始目录- **find_files**
  - 根据模式查找文件
  - 输入：
    - `pattern` (字符串): 搜索模式
    - `excludePatterns` (字符串[]): 排除模式（支持 glob 格式）
  - 不区分大小写的匹配
  - 返回匹配项的完整路径

- **find_files_by_extension**
  - 查找具有特定扩展名的所有文件
  - 输入：
    - `path` (字符串): 起始目录
    - `extension` (字符串): 要查找的文件扩展名
    - `excludePatterns` (字符串[], 可选): 排除模式
  - 不区分大小写的扩展名匹配
  - 返回匹配文件的完整路径

- **get_file_info**
  - 获取文件/目录的详细元数据
  - 输入: `path` (字符串)
  - 返回：
    - 大小
    - 创建时间
    - 修改时间
    - 访问时间
    - 类型 (文件/目录)
    - 权限

- **get_permissions**
  - 获取当前服务器权限
  - 无需输入
  - 返回：
    - 权限标志 (readonly, fullAccess, create, edit, move, delete)
    - 符号链接跟随状态
    - 允许访问的目录数量

- **list_allowed_directories**
  - 列出服务器允许访问的所有目录
  - 无需输入
  - 返回允许访问的目录路径数组

- **xml_to_json**
  - 将 XML 文件转换为 JSON 格式
  - 输入：
    - `xmlPath` (字符串): 源 XML 文件
    - `jsonPath` (字符串): 目标 JSON 文件
    - `options` (对象): 可选设置
      - `ignoreAttributes` (布尔值): 跳过 XML 属性 (默认: false)
      - `preserveOrder` (布尔值): 保持属性顺序 (默认: true)
      - `format` (布尔值): 美化打印 JSON (默认: true)
      - `indentSize` (数字): JSON 缩进 (默认: 2)
  - 需要对 XML 文件的 `read` 权限
  - 需要对 JSON 文件的 `create` 或 `edit` 权限

- **xml_to_json_string**
  - 将 XML 文件转换为 JSON 字符串
  - 输入：
    - `xmlPath` (字符串): 源 XML 文件
    - `options` (对象): 可选设置
      - `ignoreAttributes` (布尔值): 跳过 XML 属性 (默认: false)
      - `preserveOrder` (布尔值): 保持属性顺序 (默认: true)
  - 需要对 XML 文件的 `read` 权限
  - 返回 JSON 字符串表示

- **xml_query**
  - 使用 XPath 表达式查询 XML 文件
  - 输入：
    - `path` (字符串): XML 文件的路径
    - `query` (字符串, 可选): 要执行的 XPath 查询
    - `structureOnly` (布尔值, 可选): 仅返回标签结构
    - `maxBytes` (数字, 可选): 最大读取字节数 (默认: 1MB)
    - `includeAttributes` (布尔值, 可选): 包含属性信息 (默认: true)
  - XPath 示例：
    - 获取所有元素: `//tagname`
    - 获取具有特定属性的元素: `//tagname[@attr="value"]`
    - 获取文本内容: `//tagname/text()`
  - 对大型 XML 文件内存效率高
  - 返回查询结果或结构的 JSON 表示

- **xml_structure**
  - 在不读取整个文件的情况下分析 XML 结构
  - 输入：
    - `path` (字符串): XML 文件的路径
    - `depth` (数字, 可选): 分析深度 (默认: 2)
    - `includeAttributes` (布尔值, 可选): 包含属性分析
    - `maxBytes` (数字, 可选): 最大读取字节数 (默认: 1MB)
  - 返回关于元素、属性和结构的统计信息
  - 有助于在详细分析之前理解大型 XML 文件

## 权限与安全

服务器实现了全面的安全模型，具有细粒度的权限控制：

### 目录访问控制
- 操作严格限制在启动时通过 `args` 指定的目录内
- 所有操作（包括符号链接目标）必须在允许的目录内进行
- 路径验证确保没有目录遍历或超出允许路径的访问

### 权限标志
- **--readonly**: 强制只读模式，覆盖所有其他权限标志
- **--full-access**: 启用所有操作 (创建、编辑、移动、删除)
- 单个权限标志（除非设置了 --full-access，否则需要显式启用）:
  - **--allow-create**: 允许创建新的文件和目录- **--allow-edit**: 允许修改现有文件
  - **--allow-move**: 允许移动/重命名文件和目录
  - **--allow-delete**: 允许删除文件和目录

**默认行为**: 如果未指定任何权限标志，服务器将以只读模式运行。要启用任何写操作，必须使用 `--full-access` 或特定的 `--allow-*` 标志。

### 符号链接处理
- 默认情况下，符号链接会被跟随（链接及其目标都必须在允许的目录中）
- **--no-follow-symlinks**: 禁用符号链接跟随（操作作用于链接本身）

## 与 Claude Desktop 和 Cursor 的使用

在 `claude_desktop_config.json`（针对 Claude Desktop）或 `.cursor/mcp.json`（针对 Cursor）中添加适当的配置：

### Cursor 配置

在 `.cursor/mcp.json` 中：

json
{
  "mcpServers": {
    "my-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/path/to/allowed/directory",
        "--full-access"
      ]
    }
  }
}


### Docker 配置

对于使用 Docker 的 Claude Desktop：

json
{
  "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",
        "--readonly",                    // 用于只读访问
        "--no-follow-symlinks",         // 可选：防止符号链接跟随
        "/projects"
      ]
    }
  }
}


### NPX 配置

对于使用 NPX 的 Claude Desktop 或 Cursor：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--full-access",                // 用于完全读写访问
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
…