Filesystem MCP Server

文件系统 MCP 服务

使用 Python 实现的文件系统操作 Model Context Protocol (MCP) 服务。

功能

• 读取／写入文件
• 创建／列出／删除目录
• 移动文件／目录
• 搜索文件
• 获取文件元数据

注意：此服务只允许在通过 args 指定的目录中执行操作。

API

资源

• file://system：文件系统操作接口

工具

• read_file

  • 读取文件的完整内容
  • 输入：path（字符串）
  • 使用 UTF-8 编码读取文件的完整内容

• read_multiple_files

  • 同时读取多个文件
  • 输入：paths（字符串数组）
  • 读取失败不会中断整个操作

• write_file

  • 创建新文件或覆盖现有文件（使用时请谨慎）
  • 输入：
    • path（字符串）：文件位置
    • content（字符串）：文件内容

• edit_file

  • 使用高级模式匹配和格式化进行选择性编辑
  • 功能：
    • 按行和多行内容匹配
    • 保留缩进的空白字符规范化
    • 正确定位并同时进行多项编辑
    • 检测并保留缩进样式
    • 输出带上下文的 Git 样式差异
    • 使用试运行模式预览更改
  • 输入：
    • path（字符串）：要编辑的文件
    • edits（数组）：编辑操作列表
      • oldText（字符串）：要搜索的文本（可以是子字符串）
      • newText（字符串）：用于替换的文本
    • dryRun（布尔值）：预览更改但不应用（默认值：false）
  • 试运行时返回详细的差异和匹配信息，否则应用更改
  • 最佳实践：应用更改前，请务必先使用 dryRun 预览

• create_directory

  • 创建新目录或确保目录存在
  • 输入：path（字符串）
  • 如有需要，会创建父目录
  • 如果目录已存在，则静默成功

• list_directory

  • 列出目录内容，条目带有 [FILE] 或 [DIR] 前缀
  • 输入：path（字符串）

• move_file

  • 移动或重命名文件和目录
  • 输入：
    • source（字符串）
    • destination（字符串）
  • 如果目标已存在则失败

• search_files

  • 递归搜索文件／目录
  • 输入：
    • path（字符串）：起始目录
    • pattern（字符串）：搜索模式
    • excludePatterns（字符串数组）：排除匹配的模式。支持 Glob 格式。
  • 不区分大小写匹配
  • 返回匹配项的完整路径

• get_file_info

  • 获取文件／目录的详细元数据
  • 输入：path（字符串）
  • 返回：
    • 大小
    • 创建时间
    • 修改时间
    • 访问时间
    • 类型（文件／目录）
    • 权限

• list_allowed_directories

  • 列出此服务获准访问的所有目录
  • 无需输入
  • 返回：
    • 此服务可读写的目录

安装

git + Python

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem
cd filesystem

# Create and activate a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies using pip with pyproject.toml
pip install -e .

运行服务

需要先完成安装

# Enable virtual env 
source .venv/bin/activate 
# Run server with allowed paths (paths optional but recommended)
python ./src/main.py  /path/to/home /path/to/project

或者，你可以使用 uvx 直接从 GH 仓库运行 需要安装 uv：https://docs.astral.sh/uv/getting-started/installation/

uvx --from git+https://github.com/javillegasna/filesystem filesystem /Users/username/Desktop

在不同平台上使用

Claude Desktop

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/javillegasna/filesystem",
        "filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir",
      ]
    }
  }
}

vscode

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "uvx",
        "args": [
        "--from",
        "git+https://github.com/javillegasna/filesystem",
        "filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir",
      ]
      }
    }
  }
}