j0hanz/filesystem-mcp
GitHub: j0hanz/filesystem-mcp
为 AI 助手提供安全受控的本地文件系统访问能力的 MCP 服务器，支持读写、搜索、差异对比和补丁应用等完整文件操作。
Stars: 2 | Forks: 1
# Filesystem MCP 服务器
[](https://www.npmjs.com/package/%40j0hanz%2Ffilesystem-mcp) [](#contributing-and-license)
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) [](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D)
[](https://lmstudio.ai/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [](https://cursor.com/en/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem-mcp&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
一个本地文件系统 MCP server，让 LLM 和 AI 智能体能够安全、高效地读取、写入、搜索、对比、修补和管理文件。专为可靠、结构化和受控的文件系统交互而构建。
## 概述
一个安全、生产就绪的 [Model Context Protocol](https://modelcontextprotocol.io) server，为 AI 助手提供对本地文件系统的受控访问。所有操作都限制在明确允许的目录内，具有路径遍历防护、敏感文件阻止和可选的 Bearer token 认证功能。
支持 **stdio**（默认）和 **Streamable HTTP + SSE** 传输，并提供会话级隔离。
## 核心功能
- **18 个文件系统工具** — 读取、写入、搜索、对比、修补、哈希和批量操作，均带有结构化输出 schema
- **安全优先** — 路径验证、符号链接逃逸防护、敏感文件黑名单、仅限本地 CORS、可选 API key 认证
- **双重传输模式** — stdio 用于本地使用，Streamable HTTP with SSE 用于网络/多会话部署
- **结构化输出** — 所有工具返回类型化的 `outputSchema` / `structuredContent`，便于 LLM 可靠解析
- **自文档化** — 6 个内置资源（`internal://instructions`、`internal://tool-catalog` 等）和一个 `get-help` 提示词
## 系统要求
- Node.js >= 24
## 快速开始
```
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
```
### Docker
```
docker run -i --rm -v /path/to/project:/workspace:ro ghcr.io/j0hanz/filesystem-mcp /workspace
```
或使用 Docker Compose：
```
services:
filesystem-mcp:
build: .
stdin_open: true
volumes:
- ./:/projects/workspace:ro
command: ['/projects/workspace']
```
### CLI 使用
```
filesystem-mcp [options] [allowedDirs...]
Arguments:
allowedDirs Directories the server can access
Options:
--allow-cwd Allow the current working directory as an additional root
--port Enable HTTP transport on the given port
-v, --version Display server version
-h, --help Display help
Examples:
$ npx @j0hanz/filesystem-mcp@latest /path/to/project
$ npx @j0hanz/filesystem-mcp@latest --allow-cwd
$ npx @j0hanz/filesystem-mcp@latest --port 3000 /path/to/project
```
## 客户端配置
## 使用场景
### 探索和理解代码库
发现项目结构并导航不熟悉的代码仓库。首先使用 `roots` 查看允许的目录，使用 `tree` 获取概览，使用 `find` 按模式定位文件，使用 `read` 或 `read_many` 检查内容。
**相关工具：** `roots`、`ls`、`find`、`tree`、`read`、`read_many`、`stat`
### 跨文件搜索
在整个项目中定位特定的代码模式、函数定义或配置值。使用 `grep` 进行支持正则表达式的内容搜索，使用 `find` 进行文件名匹配。
**相关工具：** `grep`、`find`
### 编辑和重构代码
对源文件进行精确、有针对性的编辑。使用 `edit` 进行带有预览功能的精准替换，或使用 `search_and_replace` 对匹配 glob 模式的多个文件进行批量修改。
**相关工具：** `edit`、`search_and_replace`、`write`
### Diff 和 Patch 工作流
比较文件版本并应用补丁。使用 `diff_files` 生成统一 diff，使用 `apply_patch(dryRun: true)` 预览，然后应用。支持单文件和多文件补丁（尽力而为，每个文件有独立的 `results[]`）。
**相关工具：** `diff_files`、`apply_patch`
### 文件管理
创建目录、移动/重命名文件、删除文件，并通过 SHA-256 哈希验证文件完整性。
**相关工具：** `mkdir`、`mv`、`rm`、`calculate_hash`、`write`
## 架构
```
[MCP Client]
|
| Transport: stdio (default) or Streamable HTTP + SSE (--port)
v
[MCP Server: filesystem-mcp]
| Entry: src/index.ts -> src/server/bootstrap.ts
|
+-- initialize / initialized
|
+-- tools/call ──────────────────────────────────────────
| +-- [roots] — List allowed workspace roots
| +-- [ls] — List directory contents
| +-- [find] — Find files by glob
| +-- [tree] — Render directory tree
| +-- [read] — Read file contents
| +-- [read_many] — Read multiple files
| +-- [stat] — Get file metadata
| +-- [stat_many] — Get multiple file metadata
| +-- [grep] — Search file contents
| +-- [mkdir] — Create directory
| +-- [write] — Write file
| +-- [edit] — Edit file (string replacements)
| +-- [mv] — Move/rename file
| +-- [rm] — Delete file
| +-- [calculate_hash] — SHA-256 hash
| +-- [diff_files] — Unified diff
| +-- [apply_patch] — Apply unified patch
| +-- [search_and_replace]— Bulk search & replace
|
+-- resources/read ──────────────────────────────────────
| +-- internal://instructions
| +-- internal://tool-catalog
| +-- internal://workflows
| +-- internal://tool-info/{name}
| +-- filesystem-mcp://result/{id}
| +-- filesystem-mcp://metrics
|
+-- prompts/get ─────────────────────────────────────────
| +-- get-help (optional topic argument)
|
+-- Capabilities: logging, resources, tools, prompts, completions, tasks
```
### 请求生命周期
```
[Client] -- initialize {protocolVersion, capabilities} --> [Server]
[Server] -- {protocolVersion, capabilities, serverInfo} --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name, arguments} --> [Server]
[Server] -- validate(inputSchema) --> [Handler]
[Handler] -- {content: [{type, text}], structuredContent?, isError?} --> [Client]
```
## MCP 接口
### 工具
#### `roots`
列出允许的工作区根目录。首先调用此工具 — 所有其他工具都限定在这些目录范围内。
_无参数。_
#### `ls`
列出目录的直接内容：名称、路径、类型、大小、修改日期。
| 参数 | 类型 | 必填 | 描述 |
| ----------------------- | ------- | ---- | ------------------------------------------------------ |
| `path` | string | 否 | 基础目录（默认：root） |
| `includeHidden` | boolean | 否 | 包含点文件。默认：`false` |
| `includeIgnored` | boolean | 否 | 包含被忽略的项（node_modules、.git）。默认：`false` |
| `maxDepth` | integer | 否 | 提供 pattern 时的最大递归深度（1-100） |
| `maxEntries` | integer | 否 | 截断前的最大条目数。默认：1000，最大：10000 |
| `sortBy` | enum | 否 | `name` \| `size` \| `modified` \| `type`。默认：`name` |
| `pattern` | string | 否 | Glob 过滤器（例如 `**/*.ts`） |
| `includeSymlinkTargets` | boolean | 否 | 解析符号链接目标。默认：`false` |
| `cursor` | string | 否 | 来自上一次响应的分页游标 #### `find`
通过 glob 模式查找文件。返回匹配的文件及元数据。
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------- | ---- | --------------------------------------------------- |
| `path` | string | 否 | 基础目录（默认：root） |
| `pattern` | string | **是** | Glob 模式（例如 `**/*.ts`） |
| `maxResults` | integer | 否 | 最大结果数（1-100000）。默认：1000 |
| `includeIgnored` | boolean | 否 | 包含被忽略的项。默认：`false` |
| `includeHidden` | boolean | 否 | 包含点文件。默认：`false` |
| `sortBy` | enum | 否 | `path` \| `name` \| `size` \| `modified`。默认：`path` |
| `maxDepth` | integer | 否 | 最大目录深度（0-1000） |
| `cursor` | string | 否 | 分页游标 |
#### `tree`
渲染带有边界递归的目录树。返回 ASCII 树 + 结构化 JSON。
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------- | ---- | ------------------------------------------- |
| `path` | string | 否 | 基础目录（默认：root） |
| `maxDepth` | integer | 否 | 深度（0 = 仅根节点）。默认：10，最大：100 |
| `maxEntries` | integer | 否 | 最大条目数。默认：5000，最大：100000 |
| `includeHidden` | boolean | 否 | 包含点文件。默认：`false` |
| `includeIgnored` | boolean | 否 | 包含被忽略的项。默认：`false` |
#### `read`
读取文本文件内容。使用 `head` 预览大文件的前 N 行。
| 参数 | 类型 | 必填 | 描述 |
| ---------- | ------- | ---- | ---------------------------------------------- |
| `path` | string | **是** | 文件的绝对路径 |
| `head` | integer | 否 | 读取前 N 行（1-100000） |
| `startLine`| integer | 否 | 起始行（从 1 开始，包含） |
| `endLine` | integer | 否 | 结束行（从 1 开始，包含）。需要 `startLine` |
#### `read_many`
在一次请求中读取多个文本文件。
| 参数 | 类型 | 必填 | 描述 |
| ---------- | -------- | ---- | ---------------------------- |
| `paths` | string[] | **是** | 要读取的文件（1-100 个路径） |
| `head` | integer | 否 | 读取每个文件的前 N 行 |
| `startLine`| integer | 否 | 每个文件的起始行（从 1 开始）|
| `endLine` | integer | 否 | 每个文件的结束行（从 1 开始）|
#### `stat`
获取文件/目录元数据：大小、修改时间、权限、MIME 类型、token 估算值。
| 参数 | 类型 | 必填 | 描述 |
| ----- | ------ | ---- | ---------------------- |
| `path`| string | **是** | 文件或目录的绝对路径 |
#### `stat_many`
在一次请求中获取多个文件/目录的元数据。
| 参数 | 类型 | 必填 | 描述 |
| ------- | -------- | ---- | --------------------------- |
| `paths` | string[] | **是** | 文件/目录路径（1-100 个） |
#### `grep`
搜索文件内容（类 grep）。返回匹配行及可选上下文。
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------- | ---- | --------------------------------------------------- |
| `path` | string | 否 | 基础目录（默认：root） |
| `pattern` | string | **是** | 搜索文本或 `isRegex=true` 时的 RE2 正则表达式 |
| `isRegex` | boolean | 否 | 将模式视为 RE2 正则。默认：`false` |
| `caseSensitive` | boolean | 否 | 区分大小写匹配。默认：`false` |
| `wholeWord` | boolean | 否 | 仅匹配整个单词。默认：`false` |
| `contextLines` | integer | 否 | 前后上下文行数（0-50）。默认：0 |
| `maxResults` | integer | 否 | 最大匹配行数（1-100000）。默认：100 |
| `filePattern` | string | 否 | 候选文件的 Glob（例如 `**/*.ts`） |
| `includeHidden` | boolean | 否 | 包含点文件。默认：`false` |
| `includeIgnored` | boolean | 否 | 包含被忽略的项。默认：`false` |
#### `mkdir`
创建新目录（递归）。幂等操作。
| 参数 | 类型 | 必填 | 描述 |
| ------ | -------- | ---- | -------------------------------------------------- |
| `path` | string | 否 | 要创建的目录的绝对路径 |
| `paths`| string[] | 否 | 要创建的多个目录。`path` 或 `paths` 二选一必填 |
#### `write`
将内容写入文件，**覆盖所有现有内容**。如需要会创建父目录。
| 参数 | 类型 | 必填 | 描述 |
| --------- | ------ | ---- | ---------------- |
| `path` | string | **是** | 文件的绝对路径 |
| `content` | string | **是** | 要写入的内容 |
#### `edit`
应用顺序字面字符串替换（每次编辑替换第一个匹配项）。使用 `dryRun` 进行预览。
| 参数 | 类型 | 必填 | 描述 |
| ------------------- | ------- | ---- | ------------------------------------------------------ |
| `path` | string | **是** | 文件的绝对路径 |
| `edits` | array | **是** | `{oldText, newText}` 替换列表 |
| `dryRun` | boolean | 否 | 预览编辑而不写入。默认：`false` |
| `ignoreWhitespace` | boolean | 否 | 将空白序列视为等效。默认：`false` |
#### `mv`
移动或重命名文件或目录。
| 参数 | 类型 | 必填 | 描述 |
| ------------- | -------- | ---- | -------------------------------------------------- |
| `source` | string | 否 | 单个移动路径（已弃用：请使用 `sources`） |
| `sources` | string[] | 否 | 要移动的路径。`source` 或 `sources` 二选一必填 |
| `destination` | string | **是** | 目标路径 |
#### `rm`
永久删除文件或目录。**不可逆。**
| 参数 | 类型 | 必填 | 描述 |
| ------------------- | ------- | ---- | -------------------------------------- |
| `path` | string | **是** | 文件或目录的绝对路径 |
| `recursive` | boolean | 否 | 删除非空目录。默认：`false` |
| `ignoreIfNotExists` | boolean | 否 | 不存在时不报错。默认：`false` |
#### `calculate_hash`
计算文件或目录的 SHA-256 哈希值。
| 参数 | 类型 | 必填 | 描述 |
| ----- | ------ | ---- | ---------------------- |
| `path`| string | **是** | 文件或目录的绝对路径 |
#### `diff_files`
生成两个文件之间的统一 diff。输出可直接用于 `apply_patch`。
| 参数 | 类型 | 必填 | 描述 |
| ------------------- | ------- | ---- | ---------------------------------------------- |
| `original` | string | **是** | 原始文件路径 |
| `modified` | string | **是** | 修改后文件路径 |
| `context` | integer | 否 | diff 输出中的上下文行数 |
| `ignoreWhitespace` | boolean | 否 | 忽略前导/尾随空白。默认：`false` |
| `stripTrailingCr` | boolean | 否 | 去除尾部回车符。默认：`false` |
#### `apply_patch`
将统一 diff 补丁应用到一个或多个文件。单文件：失败时抛出异常。多文件：尽力而为，返回每个文件的 `results[]`。工作流：`diff_files` -> `apply_patch(dryRun)` -> `apply_patch`。
| 参数 | 类型 | 必填 | 描述 |
| ----------------------- | ------- | ---- | ------------------------------------------------------ |
| `path` | string | **是** | 文件路径（单个）或基础目录（多文件补丁） |
| `patch` | string | **是** | 带有 `@@` hunk 头的统一 diff（单个或多个文件） |
| `fuzzFactor` | integer | 否 | 每个 hunk 的最大模糊匹配数（0-20） |
| `autoConvertLineEndings`| boolean | 否 | 自动转换行尾。默认：`true` |
| `dryRun` | boolean | 否 | 仅验证不写入。默认：`false` |
#### `search_and_replace`
跨匹配 glob 的文件进行批量搜索替换。替换文件中的**所有**匹配项。始终先使用 `dryRun: true`。
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------- | ---- | -------------------------------------------------- |
| `path` | string | 否 | 基础目录（默认：root） |
| `filePattern` | string | **是** | Glob 模式（例如 `**/*.ts`） |
| `searchPattern` | string | **是** | 搜索文本。`isRegex=true` 时为 RE2 正则 |
| `replacement` | string | **是** | 替换文本。正则模式下支持 `$1`、`$2` |
| `isRegex` | boolean | 否 | 视为 RE2 正则。默认：`false` |
| `dryRun` | boolean | 否 | 预览匹配和 diff。默认：`false` |
| `includeHidden` | boolean | 否 | 包含点文件。默认：`false` |
| `includeIgnored` | boolean | 否 | 包含被忽略的项。默认：`false` |
| `returnDiff` | boolean | 否 | 即使非 dry-run 也返回 diff。默认：`false` |
### 资源
| 资源 | URI | MIME 类型 | 描述 |
| ------------- | ------------------------------ | ------------- | ------------------------------------------------ |
| 使用说明 | `internal://instructions` | text/markdown | 全面的使用规则和指南 |
| 工具目录 | `internal://tool-catalog` | text/markdown | 工具选择指南和数据流图 |
| 工作流 | `internal://workflows` | text/markdown | 探索、搜索、编辑、修补的标准操作流程 |
| 工具信息 | `internal://tool-info/{name}` | text/markdown | 每个工具的契约详情、细微差别、注意事项 |
| 结果缓存 | `filesystem-mcp://result/{id}` | text/markdown | 临时缓存的工具输出（大型结果在此外部化） |
| 指标 | `filesystem-mcp://metrics` | text/markdown | 实时快照：每个工具的调用/错误/平均耗时 |
### 提示词
| 提示词 | 参数 | 描述 |
| ---------- | ----------------- | -------------------------------------------------------------------- |
| `get-help` | `topic`（可选） | 返回使用说明。可选按章节标题前缀过滤 |
## MCP 能力
| 能力 | 状态 | 证据 |
| ------------ | -------- | ---------------------------------------------------------- |
| `logging` | 已确认 | `src/server/bootstrap.ts` — 在 capabilities 中注册 |
| `resources` | 已确认 | `src/server/bootstrap.ts` — 注册了 6 个资源 |
| `tools` | 已确认 | `src/server/bootstrap.ts` — 注册了 18 个工具 |
| `prompts` | 已确认 | `src/server/bootstrap.ts` — 注册了 `get-help` 提示词 |
| `completions`| 已确认 | `src/completions.ts` — 路径 + topic 自动补全 |
| `` | 已确认 | `src/server/bootstrap.ts` — 可选任务支持 |
### 工具注解
| 注解 | 工具 | 值 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `readOnlyHint: true` | `roots`、`ls`、`find`、`tree`、`read`、`read_many`、`stat`、`stat_many`、`grep`、`calculate_hash`、`diff_files` | 只读、幂等、非破坏性 |
| `destructiveHint: true` | `write`、`edit`、`rm`、`mv`、`search_and_replace`、`apply_patch` | 破坏性写入、非幂等 |
| `idempotentHint: true` | `mkdir` | 幂等写入、非破坏性 |
### 结构化输出
所有 18 个工具都定义了 `outputSchema`（Zod -> JSON Schema）并返回 `structuredContent` 和文本 `content`。设置 `FS_CONTEXT_STRIP_STRUCTURED=true` 可从工具定义中移除输出 schema（减少不使用结构化输出的 LLM 的 token 消耗）。
## 配置
| 变量 | 默认值 | 描述 |
| ----------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| `FILESYSTEM_MCP_API_KEY` | _（无）_ | 当 HTTP 绑定到非回环地址时需要的 Bearer token |
| `FILESYSTEM_MCP_MAX_HTTP_SESSIONS` | `100` | 最大并发 HTTP 会话数（1-10,000） |
| `FILESYSTEM_MCP_HTTP_HOST` | `127.0.0.1` | HTTP 服务器绑定地址 |
| `FS_CONTEXT_MAX_REQUEST_BYTES` | `4194304`（4 MB） | HTTP 请求体最大尺寸（1 KB - 256 MB） |
| `FS_CONTEXT_MAX_INLINE_CHARS` | _（自动）_ | 内联结果字符数上限，超过则外部化到 `filesystem-mcp://result/{id}` |
| `FS_CONTEXT_MAX_INLINE_MATCHES` | `50` | 内联搜索匹配数上限，超过则截断 |
| `FS_CONTEXT_STRIP_STRUCTURED` | `false` | 从工具定义中移除 `outputSchema` |
| `FS_CONTEXT_DIAGNOSTICS` | `false` | 启用诊断日志 |
| `FS_CONTEXT_DIAGNOSTICS_DETAIL` | `false` | 启用详细诊断输出 |
| `FS_CONTEXT_TOOL_LOG_ERRORS` | `false` | 将工具错误记录到 stderr |
| `FS_CONTEXT_SEARCH_WORKERS_DEBUG` | `false` | 搜索 worker pool 的调试日志 |
## HTTP 端点
当使用 `--port ` 启动时，服务器暴露单个 MCP 端点：
| 方法 | 路径 | 用途 |
| -------- | ------ | -------------------------------------------------- |
| `POST` | `/mcp` | 初始化会话或发送请求 |
| `GET` | `/mcp` | 会话的 Server-Sent Events 流 |
| `DELETE` | `/mcp` | 终止会话 |
**必需的请求头：**
- `mcp-protocol-version` — 在初始化后的 HTTP 请求中使用协商好的 MCP 协议版本
- `mcp-session-id` — `GET`/`DELETE` 必需（由 `POST` 在初始化时返回）
**认证：** 对非回环 HTTP 绑定的请求需要 `FILESYSTEM_MCP_API_KEY`；客户端必须发送 `Authorization: Bearer `。仅限回环的绑定在本地使用时可省略认证。使用 SHA-256 计时安全比较。
**CORS：** 仅允许 localhost 来源（`127.0.0.1`、`::1`、`localhost`）。
## 安全
| 控制措施 | 状态 | 证据 |
| ----------------------- | -------- | ------------------------------------------------------------------------------------ |
| 路径沙箱 | 已确认 | `src/lib/paths.ts` — 所有路径根据允许的根目录进行验证 |
| 遍历防护 | 已确认 | `src/lib/paths.ts` — 规范化后检查解析后的路径 |
| 符号链接逃逸防护 | 已确认 | `src/__tests__/security.test.ts` — 符号链接边界强制执行 |
| 敏感文件黑名单 | 已确认 | `src/lib/constants.ts` — 阻止 `.git`、`.env*`、SSH 密钥、证书、secrets |
| 来源验证 | 已确认 | `src/server/bootstrap.ts` — 仅 localhost 来源白名单 |
| Bearer 认证 | 已确认 | `src/server/bootstrap.ts` — 可选 `FILESYSTEM_MCP_API_KEY`，计时安全比较 |
| 输入验证 | 已确认 | `src/schemas.ts` — 所有工具输入使用 Zod 严格 schema |
| 请求体限制 | 已确认 | `src/server/bootstrap.ts` — 可配置最大请求大小（溢出返回 413） |
| 远程绑定保护 | 已确认 | `src/server/bootstrap.ts` — 没有 `FILESYSTEM_MCP_API_KEY` 拒绝非回环绑定 |
## 开发
| 脚本 | 命令 | 用途 |
| ------------ | --------------------------------------------------------- | ------------------------ |
| `dev` | `tsc --watch` | 监视模式 TypeScript 编译 |
| `dev:run` | `node --env-file=.env --watch dist/index.js` | 带自动重载运行服务器 |
| `start` | `node dist/index.js` | 运行生产服务器 |
| `build` | `node scripts/tasks.mjs build` | 清理构建 |
| `test` | `node scripts/tasks.mjs test` | 构建 + 运行所有测试 |
| `test:fast` | `node --test --import tsx/esm src/__tests__/**/*.test.ts` | 不构建运行测试 |
| `lint` | `eslint .` | 检查源代码 |
| `type-check` | `node scripts/tasks.mjs type-check` | 类型检查 src + 测试 |
| `format` | `prettier --write .` | 格式化代码 |
| `inspector` | `npm run build && npx @modelcontextprotocol/inspector` | 启动 MCP Inspector |
## 构建和发布
- **CI：** `.github/workflows/release.yml` — 在打标签/发布前运行 lint、type-check、test、build。
- **Docker：** 使用 `node:24-alpine` 的多阶段构建。构建器编译 TypeScript + 原生模块；发布阶段以非 root 用户 `mcp` 运行。
- **npm：** `npm run prepublishOnly` 运行 lint + type-check + build。
## 故障排除
- **"No allowed directories"** — 传递至少一个目录参数或使用 `--allow-cwd`。
- **Sensitive file blocked** — 匹配黑名单（`.env*`、`.git`、SSH 密钥）的文件被设计为阻止。查看 `src/lib/constants.ts` 获取完整列表。
- **Large result externalized** — 当工具输出超过内联限制时，会缓存为 `filesystem-mcp://result/{id}` 资源。读取该资源 URI 获取完整内容。
- **Stdio: logs on stdout** — 保持日志仅在 stderr。服务器使用 `console.error` 输出诊断信息。
- **HTTP 413** — 请求体超过 `FS_CONTEXT_MAX_REQUEST_BYTES`。增加限制或减小负载大小。
- **HTTP 401** — 设置了 `FILESYSTEM_MCP_API_KEY` 但请求缺少或 `Authorization: Bearer` 头不正确。
## 致谢
| 依赖项 | 描述 |
| --------------------------------------------------------------------------------- | ---------------------------------- |
| [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) | MCP TypeScript SDK |
| [commander](https://www.npmjs.com/package/commander) | CLI 参数解析 |
| [diff](https://www.npmjs.com/package/diff) | 统一 diff 生成和补丁应用 |
| [ignore](https://www.npmjs.com/package/ignore) | `.gitignore` 模式匹配 |
| [re2](https://www.npmjs.com/package/re2) | 安全的 RE2 正则引擎（无 ReDoS） |
| [safe-regex2](https://www.npmjs.com/package/safe-regex2) | 正则安全验证 |
| [zod](https://www.npmjs.com/package/zod) | Schema 验证和 JSON Schema 生成 |
## 贡献和许可
- **许可证：** MIT
- 欢迎通过 pull request 贡献。
在 VS Code 中安装
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) 添加到 `.vscode/mcp.json`： ``` { "servers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ``` 或通过 CLI 安装： ``` code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}' ```在 VS Code Insiders 中安装
[](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) 添加到 `.vscode/mcp.json`： ``` { "servers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ``` 或通过 CLI 安装： ``` code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}' ```在 Cursor 中安装
[](https://cursor.com/en/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) 添加到 `~/.cursor/mcp.json`： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Visual Studio 中安装
[](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D) ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Goose 中安装
[](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem-mcp&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.) ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```添加到 LM Studio
[](https://lmstudio.ai/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Claude Desktop 中安装
添加到 `claude_desktop_config.json`： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Claude Code 中安装
``` claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest ``` 或添加到配置文件： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Windsurf 中安装
添加到 `~/.codeium/windsurf/mcp_config.json`： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Amp 中安装
``` amp mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest ``` 或添加到配置文件： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Cline 中安装
添加到 `cline_mcp_settings.json`： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Codex CLI 中安装
``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 GitHub Copilot 中安装
添加到 `.vscode/mcp.json`： ``` { "servers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Warp 中安装
``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Kiro 中安装
添加到 `.kiro/settings/mcp.json`： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Gemini CLI 中安装
添加到 `~/.gemini/settings.json`： ``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Zed 中安装
添加到 `~/.config/zed/settings.json`： ``` { "context_servers": { "filesystem-mcp": { "settings": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } } ```在 Augment 中安装
添加到 VS Code `settings.json` 的 `augment.advanced` 下： ``` { "augment.advanced": { "mcpServers": [ { "id": "filesystem-mcp", "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } ] } } ```在 Roo Code 中安装
``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```在 Kilo Code 中安装
``` { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["-y", "@j0hanz/filesystem-mcp@latest"] } } } ```标签：Cursor, GNU通用公共许可证, HTTP工具, LLM辅助编程, MCP服务器, MITM代理, Model Context Protocol, Node.js, NPM包, OSV-Scalibr, TypeScript, VS Code 扩展, 代码补丁, 大语言模型工具, 安全插件, 安全文件操作, 文件搜索, 文件系统管理, 文件读写, 本地文件访问, 自动化攻击, 请求拦截