MCP 文件系统服务器

一个简单的模型上下文协议 (MCP) 服务器，提供文件系统操作。该服务器遵循 MCP 协议设计，在指定的项目目录中提供干净的 API 来执行文件系统操作。

概述

此 MCP 服务器使像 Claude（通过 Claude Desktop）或其他兼容 MCP 的系统这样的 AI 助手能够与您的本地文件系统进行交互。借助这些功能，AI 助手可以：

• 读取您现有的代码和项目文件
• 用生成的内容写入新文件
• 使用模式匹配精确更新和修改现有文件
• 在不重写整个文件的情况下选择性地编辑代码
• 根据需要删除文件
• 审查存储库以提供分析和建议
• 调试并修复代码库中的问题
• 根据您的规范生成完整的实现

所有操作都安全地包含在您指定的项目目录内，让您在控制的同时能够对本地文件进行强大的 AI 协作。

通过将 AI 助手连接到您的文件系统，您可以将工作流程从手动编码转变为更直观的提示方法——用自然语言描述您的需求，让 AI 直接在您的项目文件中生成、修改和组织代码。

功能

• list_directory：列出项目目录中的所有文件和目录
• read_file：读取文件内容
• save_file：原子性地将内容写入文件
• append_file：将内容追加到文件末尾
• delete_this_file：从文件系统中删除指定文件
• edit_file：使用高级模式匹配进行选择性编辑
• 结构化日志：具有人类可读和 JSON 格式的综合日志系统

安装

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-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 .

运行服务器

python -m src.main --project-dir /path/to/project [--log-level LEVEL] [--log-file PATH]

或者，您可以将当前目录添加到 PYTHONPATH 并直接运行脚本：

set PYTHONPATH=%PYTHONPATH%;.
python .\src\main.py --project-dir /path/to/project [--log-level LEVEL] [--log-file PATH]

命令行参数：

• --project-dir：（必需）要从中提供文件的目录
• --log-level：（可选）设置日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
• --log-file：（可选）用于结构化 JSON 日志的路径。如果不指定，则仅使用控制台日志记录。

服务器使用 FastMCP 进行操作。出于安全原因，项目目录参数 (--project-dir) 是必需的。所有文件操作将被限制在这个目录内。尝试访问该目录外的文件将导致错误。

结构化日志

服务器提供了灵活的日志选项：

• 标准的人类可读日志到控制台
• 可选的结构化 JSON 日志到文件，使用 --log-file
• 函数调用跟踪，包括参数、时间戳和结果
• 自动捕获错误上下文
• 可配置的日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）

集成选项

此服务器可以与不同的 Claude 接口集成。每个接口都需要特定的配置。

VSCode & Cline 扩展集成

Cline 扩展程序允许您直接在 VSCode 代码编辑器中使用 Claude。有关使用 Cline 配置 MCP 服务器的更多信息，请参阅 Cline MCP 服务器文档。

VSCode/Cline 配置步骤

1. 找到 Cline MCP 配置文件：

   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. 添加 MCP 服务器配置（如果文件不存在则创建）：

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\path\\to\\mcp_server_filesystem\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\mcp_server_filesystem\\src\\main.py",
        "--project-dir",
        "C:\\Users\\YourUsername\\Documents\\Projects\\MyProject",
        "--log-level",
        "INFO"
      ],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\mcp_server_filesystem\\"
      },
      "disabled": false,
      "autoApprove": [
        "list_directory",
        "read_file"
      ]
    }
  }
}

1. 重要的 VSCode/Cline 特定注意事项：

   • 将 ${workspaceFolder} 替换为您的项目目录的实际完整路径
   • 例如："C:\\Users\\YourUsername\\Documents\\Projects\\MyProject"
   • 将所有 C:\\path\\to\\ 实例替换为您的实际路径
   • 在 Windows 上使用双反斜杠 (\\)，在 macOS/Linux 上使用正斜杠 (/)
   • 项目目录应该是您希望 Claude 访问的文件夹
   • 只有将您希望每次执行时无需批准的操作添加到 autoApprove 数组中
   • 为了更好的安全性，考虑仅自动批准只读操作，如 list_directory 和 read_file

2. 重启 VSCode 并通过让 Claude “列出当前项目目录中的文件”来测试

VSCode/Cline 集成故障排除

• 查看日志位置：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\logs (Windows) 或 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/logs (macOS)
• 确认 Python 可执行文件路径指向您的虚拟环境
• 确保配置中的所有路径正确无误

Claude 桌面应用程序集成

Claude 桌面应用程序也可以使用此文件系统服务器。

Claude 桌面应用配置步骤

1. 找到 Claude 桌面应用程序配置文件：

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加 MCP 服务器配置（如果文件不存在则创建）：

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\path\\to\\mcp_server_filesystem\\.venv\\Scripts\\python.exe",
      "args": [                
        "C:\\path\\to\\mcp_server_filesystem\\src\\main.py",
        "--project-dir",
        "C:\\path\\to\\your\\specific\\project",
        "--log-level",
        "INFO"
      ],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\mcp_server_filesystem\\"
      },
      "disabled": false,
      "autoApprove": [
        "list_directory",
        "read_file"
      ]
    }
  }
}

1. 重要的 Claude 桌面应用程序特定注意事项：

   • 您必须在 --project-dir 中指定一个明确的项目目录路径
   • 将所有 C:\\path\\to\\ 实例替换为您的实际路径
   • 项目目录应该是您希望 Claude 访问的文件夹
   • 只有将您希望每次执行时无需批准的操作添加到 autoApprove 数组中
   • 为了更好的安全性，考虑仅自动批准只读操作，如 list_directory 和 read_file

2. 重启 Claude 桌面应用程序 以应用更改

Claude 桌面应用程序集成故障排除

• 检查日志位置：%APPDATA%\Claude\logs (Windows) 或 ~/Library/Application Support/Claude/logs (macOS)
• 确保指定的项目目录存在且可访问
• 验证配置中的所有路径是否正确

使用 MCP Inspector

MCP Inspector 允许您调试和测试您的 MCP 服务器：

1. 通过运行以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector \
  uv \
  --directory C:\path\to\mcp_server_filesystem \
  run \
  src\main.py

1. 在 MCP Inspector 的 Web UI 中，使用以下配置：

   • Python 解释器: C:\path\to\mcp_server_filesystem\.venv\Scripts\python.exe
   • 参数: C:\path\to\mcp_server_filesystem\src\main.py --project-dir C:\path\to\your\project --log-level DEBUG
   • 环境变量:
     • 名称: PYTHONPATH
     • 值: C:\path\to\mcp_server_filesystem\

2. 这将启动服务器并提供一个用于测试可用工具的调试界面。

可用工具

服务器提供了以下 MCP 工具：

操作	描述	示例提示
list_directory	列出项目目录中的文件和子目录	"列出 src 目录下的所有文件"
read_file	读取文件内容	"显示 main.js 的内容"
save_file	创建或覆盖文件（原子操作）	"创建一个新的 app.js 文件"
append_file	向现有文件中添加内容	"向 utils.js 添加一个函数"
delete_this_file	从文件系统中删除文件	"删除 temporary.txt 文件"
edit_file	使用模式匹配进行选择性编辑	"修复 fetch 函数中的错误"

工具详情

列出目录

• 返回文件和目录名称列表
• 默认情况下，结果基于 .gitignore 模式过滤，并排除 .git 文件夹

读取文件

• 参数: file_path (字符串): 要读取的文件路径（相对于项目目录）
• 返回文件的内容作为字符串

保存文件

• 参数:
  • file_path (字符串): 要写入的文件路径
  • content (字符串): 要写入文件的内容
• 返回布尔值表示是否成功

追加到文件

• 参数:
  • file_path (字符串): 要追加内容的文件路径
  • content (字符串): 要追加到文件的内容
• 返回布尔值表示是否成功
• 注意: 文件必须已经存在；使用 save_file 来创建新文件

删除此文件

• 参数: file_path (字符串): 要删除的文件路径
• 返回布尔值表示是否成功
• 注意: 此操作不可逆，将永久删除文件

编辑文件

• 参数：
  • file_path (字符串): 要编辑的文件
  • edits (数组): 编辑操作列表，每个包含：
    • old_text (字符串): 要被替换的文本
    • new_text (字符串): 替换后的文本
  • dry_run (布尔值, 可选): 预览更改而不应用
  • options (对象, 可选): 格式设置
• 功能：
  • 基于行和多行内容匹配
  • 保留缩进的同时进行空白字符规范化
  • 多个同时编辑且保持正确位置
  • 具有上下文的 Git 风格差异输出

安全特性

• 所有路径都被规范化并验证，以确保它们保持在项目目录内
• 防止路径遍历攻击
• 文件以原子方式写入以防止数据损坏
• 删除操作限制在项目目录内以保证安全

开发

在 Windows 上设置开发环境

REM Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-filesystem

REM Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate

REM Install dependencies
pip install -e .

REM Install development dependencies
pip install -e ".[dev]"

测试

项目在 tests/ 目录中包含了基于 pytest 的单元测试。有关测试结构和执行的详细信息，请参见 tests/README.md。

对于基于 LLM 的测试，请参阅 tests/LLM_Test.md。该文件包含可以直接粘贴到 LLM 中以验证 MCP 服务器功能的测试指令。

使用 MCP 开发工具运行

# Set the PYTHONPATH and run the server module using mcp dev
set PYTHONPATH=. && mcp dev src/server.py

许可证

本项目采用 MIT 许可证 - 详情请参见 LICENSE 文件。

MIT 许可证是一种宽松的许可证，允许在最小限制下重用。它允许使用、复制、修改和分发，并需适当归属。

链接

• MCP Python SDK
• MCP Python 代码检查器
• Cline MCP 服务器文档
• Cline VSCode 扩展
• 模型上下文协议文档