文件系统 MCP 服务器

通过强大、与平台无关的文件系统功能为您的 AI 代理提供支持。

该模型上下文协议 (MCP)服务器为 AI 代理提供了一个安全可靠的接口，用于与本地文件系统交互。它支持读取、写入、更新和管理文件和目录，并以可用于生产的 TypeScript 基础架构为后盾，并具备全面的日志记录、错误处理和安全措施。

概述

模型上下文协议 (MCP) 是一个标准框架，允许 AI 模型安全地与外部工具和数据源（资源）交互。该服务器实现了 MCP 标准，将必要的文件系统操作公开为工具，从而使 AI 代理能够：

读取并分析文件内容。
创建、修改或覆盖文件。
管理目录和文件路径。
在文件内执行有针对性的更新。

该服务器采用 TypeScript 构建，强调类型安全性、模块化和强大的错误处理，使其适合可靠地集成到 AI 工作流程中。

建筑学

为了清晰和可维护性，服务器采用分层架构：

API 层：处理 MCP 通信，使用 Zod 验证输入，并清理路径。
核心服务：管理配置、日志记录、错误报告、会话状态（如默认工作目录）和主 MCP 服务器实例。
工具实现：包含每个文件系统工具的特定逻辑，利用共享实用程序。

特征

全面的文件操作：用于读取、写入、列出、删除、移动和复制文件和目录的工具。
有针对性的更新： update_file工具允许在文件内进行精确的搜索和替换操作，支持纯文本和正则表达式。
会话感知路径管理： set_filesystem_default工具建立一个默认工作目录，用于在会话期间解析相对路径。
安全第一：内置路径清理功能可防止目录遍历攻击。可选的基目录限制功能可增强安全性。
强大的基础：包括以下生产级实用程序：
- 结构化、上下文感知的日志记录。
- 使用特定错误代码的标准化错误处理。
- 用于请求跟踪的唯一 ID 生成。
- 输入清理。
- 可选速率限制（实用程序文件已创建但尚未集成）。
类型安全：在 TypeScript 中完全实现，以提高可靠性和可维护性。

安装

步骤

克隆存储库：
git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server
安装依赖项：
npm install
构建项目：
npm run build
这会将dist/目录中的 TypeScript 代码编译为 JavaScript，并使主脚本可执行。可执行文件位于dist/index.js 。

配置

使用环境变量配置服务器：

FS_BASE_DIRECTORY （可选，出于安全考虑建议使用）：
- 如果设置为绝对路径，服务器执行的所有文件操作都将严格限制在此目录及其子目录中。这可以防止 AI 代理访问预期范围之外的文件。
- 例如： FS_BASE_DIRECTORY=/Users/casey/safe-agent-files
LOG_LEVEL （可选）：
- 控制日志的详细程度。选项： error 、 warn 、 info 、 http 、 verbose 、 debug 、 silly 。
- 默认为info 。
LOG_DIR （可选）：
- 指定存储日志文件（ combined.log 、 error.log ）的目录。
- 默认为相对于服务器执行目录的./logs 。

与 MCP 客户端一起使用

要允许 MCP 客户端（如 AI 助手）使用此服务器：

**运行服务器：**从终端启动服务器：
node dist/index.js # Or if you are in the project root: # npm start
**配置客户端：**将服务器添加到 MCP 客户端的配置中。具体方法取决于客户端，但通常需要指定以下内容：
- 命令： node
- **参数：**构建的服务器可执行文件的绝对路径（例如， /path/to/filesystem-mcp-server/dist/index.js mcp-server/dist/index.js）。
- **环境变量（可选）：**根据需要设置FS_BASE_DIRECTORY 、 LOG_LEVEL或LOG_DIR 。
MCP 设置示例（概念）：
{ "mcpServers": { "filesystem": { "command": "node", "args": ["/path/to/filesystem-mcp-server/dist/index.js"], "env": { "FS_BASE_DIRECTORY": "/path/to/base/directory", "LOG_LEVEL": "debug" }, "disabled": false, "autoApprove": [] } // ... other servers } }

一旦配置并运行，客户端将检测服务器及其可用工具。

可用工具

服务器公开了以下用于文件系统交互的工具：

工具	描述
`set_filesystem_default`	为当前会话设置默认绝对路径。后续工具调用中使用的相对路径将根据此默认值进行解析。服务器重启时重置。
`read_file`	将指定文件的全部内容读取为 UTF-8 文本。接受相对路径（根据默认路径解析）或绝对路径。
`write_file`	将内容写入指定文件。如果文件不存在，则创建文件（及其必要的父目录）；如果文件存在，则覆盖文件。接受相对路径或绝对路径。
`update_file`	使用`{search, replace}`块数组在现有文件中执行定向搜索和替换操作。非常适合本地化修改。支持纯文本或正则表达式搜索 ( `useRegex: true` ) 以及替换所有匹配项 ( `replaceAll: true` )。接受相对路径或绝对路径。文件必须存在。
`list_files`	列出指定路径下的文件和目录。选项包括递归列出（ `includeNested: true` ）和限制条目数量（ `maxEntries` ）。返回格式化的树形结构。接受相对路径或绝对路径。
`delete_file`	永久删除特定文件。接受相对路径或绝对路径。
`delete_directory`	永久删除目录。使用`recursive: true`可删除非空目录及其内容（请谨慎使用！）。接受相对路径或绝对路径。
`create_directory`	在指定路径创建新目录。默认情况下 ( `create_parents: true` )，它还会创建所有必要的父目录。接受相对路径或绝对路径。
`move_path`	将文件或目录从源路径移动或重命名到目标路径。接受相对路径或绝对路径。
`copy_path`	将文件或目录从源路径复制到目标路径。对于目录，默认情况下会递归复制 ( `recursive: true` )。接受相对路径或绝对路径。

有关详细的输入/输出模式（Zod/JSON Schema），请参阅工具注册文件（ src/mcp-server/tools/*/registration.ts ）。

项目结构

代码库的组织清晰且易于维护：

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization and tool registration
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   └── tools/        # Individual tool implementations (one subdir per tool)
│   │       ├── readFile/
│   │       │   ├── index.ts
│   │       │   ├── readFileLogic.ts
│   │       │   └── registration.ts
│   │       └── ...       # Other tools (writeFile, updateFile, etc.)
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules
│   │   ├── errorHandler.ts
│   │   ├── idGenerator.ts
│   │   ├── index.ts
│   │   ├── logger.ts
│   │   ├── rateLimiter.ts
│   │   ├── requestContext.ts
│   │   └── sanitization.ts
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .gitignore
├── LICENSE
├── package.json
├── package-lock.json
├── README.md             # This file
└── tsconfig.json         # TypeScript compiler options

要查看当前结构的实时详细视图，请运行： npm run tree

**开发者备注：**此代码库包含一个.clinerules文件。此速查表为您的 LLM 编码助手提供有关代码库模式、文件位置和使用示例的重要上下文。请随着服务器的发展不断更新！

执照

本项目遵循 Apache License 2.0 许可协议。详情请参阅LICENSE文件。

Filesystem MCP Server

Integrations