Filesystem MCP Server (@sylphlab/filesystem-mcp)
2025.04.14
4
TypeScript文件管理文件管理
Filesystem MCP Server 是一个基于 Node.js 的服务，旨在为 AI 代理（如 Cline/Claude）提供安全、高效且节省令牌的项目文件访问能力。它实现了 Model Context Protocol (MCP)，提供了一套强大的文件系统工具，操作范围限定在指定的项目根目录内，确保安全性。
View on GitHub
Overview
基本能力
产品定位
Filesystem MCP Server 旨在为 AI 代理提供高效、安全的文件系统操作能力，支持批量操作以减少通信开销和令牌使用。
核心功能
- 文件浏览与检查：支持递归列出文件和目录，获取详细状态信息。
- 文件读写：支持读取、写入和追加多个文件内容，自动创建父目录。
- 精确编辑与搜索：支持跨多个文件进行插入、替换、删除等操作，保留缩进和差异输出；支持正则表达式搜索和替换。
- 目录管理：支持创建多个目录，包括中间父目录。
- 删除操作：支持递归删除多个文件或目录。
- 移动与复制：支持移动、重命名和复制多个文件或目录。
- 权限控制：支持更改多个项目的 POSIX 权限和所有权。
适用场景
- AI 代理需要高效访问和操作项目文件时。
- 需要批量处理文件系统操作以减少通信开销时。
- 需要安全地限制文件操作范围在项目根目录内时。
工具列表
list_files：列出文件和目录。stat_items：获取文件或目录的详细状态。read_content：读取文件内容。write_content：写入文件内容。edit_file：精确编辑文件内容。search_files：搜索文件内容。replace_content：替换文件内容。create_directories：创建目录。delete_items：删除文件或目录。move_items：移动或重命名文件或目录。copy_items：复制文件或目录。chmod_items：更改文件或目录的权限。chown_items：更改文件或目录的所有权。
常见问题解答
- 如何确保文件操作的安全性？：所有操作都限制在项目根目录内，防止越权访问。
- 如何减少通信开销？：支持批量操作，减少 AI 与服务器之间的往返次数。
- 如何安装？：支持通过
npx、bunx、Docker 或本地构建方式安装。
使用教程
使用依赖
- Node.js 环境或 Docker 环境。
安装教程
1. 推荐方式：通过 npx 或 bunx 安装
在 MCP 主机配置文件中添加以下内容：
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["@sylphlab/filesystem-mcp"],
"name": "Filesystem (npx)"
}
}
}
或使用 bunx：
{
"mcpServers": {
"filesystem-mcp": {
"command": "bunx",
"args": ["@sylphlab/filesystem-mcp"],
"name": "Filesystem (bunx)"
}
}
}
2. Docker 安装
在 MCP 主机配置文件中添加以下内容：
{
"mcpServers": {
"filesystem-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/your/project:/app",
"sylphlab/filesystem-mcp:latest"
],
"name": "Filesystem (Docker)"
}
}
}
3. 本地构建（开发用途）
- 克隆仓库：
bash git clone https://github.com/sylphlab/filesystem-mcp.git - 安装依赖：
bash cd filesystem-mcp && pnpm install - 构建项目：
bash pnpm run build - 在 MCP 主机配置文件中添加以下内容：
json { "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], "name": "Filesystem (Local Build)" } } }
调试方式
安装完成后，可以通过以下命令测试服务是否正常运行：
npx @sylphlab/filesystem-mcp --help
或使用 Docker：
docker run -it --rm sylphlab/filesystem-mcp:latest --help
确保 MCP 主机配置正确，并且服务能够正常响应 AI 代理的请求。