MCP 文件系统服务器

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

概述

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

• 阅读现有的代码和项目文件
• 写入带有生成内容的新文件
• 使用精确字符串匹配来精准地更新和修改现有文件
• 在不重写整个文件的情况下对代码进行选择性编辑
• 在需要时删除文件
• 审查仓库以提供分析和建议
• 调试并修复代码库中的问题
• 根据你的规范生成完整的实现

所有操作都被安全地限制在你指定的项目目录内，这给你提供了控制权，同时允许强大的AI协作在你的本地文件上。

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

功能

• list_directory: 列出项目目录中的所有文件和目录
• read_file: 读取文件的内容
• save_file: 原子地写入文件内容
• append_file: 将内容追加到文件末尾
• delete_this_file: 从文件系统中删除指定的文件
• edit_file: 使用精确字符串匹配进行选择性编辑
• move_file: 在项目内移动或重命名文件和目录
• get_reference_projects: 发现可用的参考项目
• list_reference_directory: 列出参考项目中的文件
• read_reference_file: 读取参考项目中的文件
• Structured Logging: 全面的日志系统，包括人类可读和JSON格式

安装

# 克隆仓库
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp_server_filesystem

# 创建并激活虚拟环境（可选但推荐）
python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 使用pyproject.toml安装依赖项
pip install -e .

运行服务器

安装完成后，你可以直接使用mcp-server-filesystem命令：

mcp-server-filesystem --project-dir /path/to/project [--reference-project NAME=/path/to/reference]... [--log-level LEVEL] [--log-file PATH]

命令行参数：

• --project-dir: （必需）要服务文件的目录
• --reference-project: （可选）添加参考项目的格式为name=/path/to/dir（可重复，自动重命名重复项）
• --log-level: （可选）设置日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
• --log-file: （可选）结构化JSON日志的路径。如果没有指定，默认为project_dir/logs/mcp_filesystem_server_{timestamp}.log。

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

结构化日志

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

• 标准人类可读的日志到控制台
• 结构化的JSON日志到文件（默认：project_dir/logs/mcp_filesystem_server_{timestamp}.log 或自定义路径使用 --log-file）
• 函数调用跟踪，包括参数、时间和结果
• 自动捕获错误上下文
• 可配置的日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
• 使用 --console-only 禁用文件日志

参考项目

参考项目允许你向AI助手提供附加代码库或目录的只读访问权限，以便于上下文和参考。此功能使LLM能够在浏览和阅读多个项目的文件的同时，仅维护对主项目目录的写入访问权限。

特点

• 只读访问：参考项目只能浏览和读取，不能修改
• 多个项目：同时配置多个参考项目
• 自动发现：LLM可以发现可用的参考项目
• 安全性：与主项目相同的路径验证和gitignore过滤
• 灵活路径：支持相对路径和绝对路径

配置

使用 --reference-project 参数添加参考项目：

# 单个参考项目
mcp-server-filesystem --project-dir ./my-project --reference-project docs=./documentation

# 多个参考项目
m[...]