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 配置步骤 找到 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 添加 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" ] \} \} \} 重要的 VSCode/Cline 特定注意事项： 将 $\{workspaceFolder\} 替换为您的项目目录的实际完整路径 例如："C:\\Users\\YourUsername\\Documents\\Projects\\MyProject" 将所有 C:\\path\\to\\ 实例替换为您的实际路径 在 Windows 上使用双反斜杠 (\\)，在 macOS/Linux 上使用正斜杠 (/) 项目目录应该是您希望 Claude 访问的文件夹 只有将您希望每次执行时无需批准的操作添加到 autoApprove 数组中 为了更好的安全性，考虑仅自动批准只读操作，如 list_directory 和 read_file 重启 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 桌面应用配置步骤 找到 Claude 桌面应用程序配置文件： Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 添加 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" ] \} \} \} 重要的 Claude 桌面应用程序特定注意事项： 您必须在 --project-dir 中指定一个明确的项目目录路径 将所有 C:\\path\\to\\ 实例替换为您的实际路径 项目目录应该是您希望 Claude 访问的文件夹 只有将您希望每次执行时无需批准的操作添加到 autoApprove 数组中 为了更好的安全性，考虑仅自动批准只读操作，如 list_directory 和 read_file 重启 Claude 桌面应用程序 以应用更改 Claude 桌面应用程序集成故障排除 检查日志位置：%APPDATA%\Claude\logs (Windows) 或 ~/Library/Application Support/Claude/logs (macOS) 确保指定的项目目录存在且可访问 验证配置中的所有路径是否正确 使用 MCP Inspector MCP Inspector 允许您调试和测试您的 MCP 服务器： 通过运行以下命令启动 MCP Inspector： npx @modelcontextprotocol/inspector \ uv \ --directory C:\path\to\mcp_server_filesystem \ run \ src\main.py 在 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\ 这将启动服务器并提供一个用于测试可用工具的调试界面。 可用工具 服务器提供了以下 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 扩展 模型上下文协议文档