Filesystem Context MCP Server

文件系统MCP服务器

](https://www.npmjs.com/package/%40j0hanz%2Ffilesystem-mcp) 

 

用于读取、写入、搜索、区分和修补文件的安全文件系统MCP服务器。

目录

• 概述
• 主要特点
• 客户端配置
• 用例
• 建筑
• MCP表面 — 工具 · 资源 · 提示
• MCP能力 — 工具注释 · 结构化输出
• 配置 — HTTP和身份验证 · 文件大小限制 · 访问控制 · 输出和在线限制 · 任务 · 记录和诊断 · 演出
• HTTP端点
• 安全
• 发展
• 故障排除
• 学分
• 贡献和许可

概述

安全、生产就绪 模型上下文协议 服务器，使AI助手能够控制对本地文件系统的访问。所有操作都被沙盒化到明确允许的目录，具有路径遍历防止、敏感文件阻止和可选的承载令牌身份验证功能。

支持stdio（默认）和节点流式HTTP传输。HTTP会话是使用隔离的每会话服务器状态实现的。默认情况下，HTTP传输是有状态的，目前不可恢复；它不会持久化事件存储 Last-Event-ID 重播。

主要特点

• 18个文件系统工具 --具有结构化输出模式的读、写、搜索、差异、补丁、哈希和批量操作
• 安全第一 -路径验证、符号链接转义防止、敏感文件denylist、localhost-only CORS、环回HTTP绑定的主机头验证、可选API密钥验证
• 双重运输 --stdio用于本地使用，Node Streamable HTTP用于网络/多会话部署
• 结构化输出 --所有工具返回类型 outputSchema / structuredContent 用于可靠的LLM解析
• 自我记录 --6个内置资源(internal://instructions, internal://tool-catalog等）和4个内置提示(get-help, compare-files, analyze-path, get-tool-help)

需求

• Node.js>=24

快速开始

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

码头工人

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

客户端配置

Install in VS Code


添加 .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

或通过CLI安装：

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'

Install in VS Code Insiders


添加 .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

或通过CLI安装：

code-insiders --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'

Install in Cursor


添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Visual Studio


添加 .mcp.json 或 %USERPROFILE%\.mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Goose

添加 ~/.config/goose/config.yaml:

extensions:
  filesystem:
    name: Filesystem MCP
    cmd: npx
    args:
      - -y
      - '@j0hanz/filesystem-mcp@latest'
    enabled: true
    type: stdio

Add to LM Studio


{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Claude Desktop

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Claude Code

claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest

或者添加一个项目范围 .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Windsurf

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Amp

amp mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest

或添加到 settings.json:

{
  "amp.mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Cline

添加 cline_mcp_settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Codex

codex mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest

或添加到 ~/.codex/config.toml （或 .codex/config.toml 在受信任的项目中）：

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@j0hanz/filesystem-mcp@latest"]

Install in GitHub Copilot Coding Agent

将此JSON添加到存储库的GitHub Copilot编码代理MCP配置中：

{
  "mcpServers": {
    "filesystem": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
      "tools": ["*"]
    }
  }
}

Install in Warp

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Kiro

添加 .kiro/settings/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Gemini CLI

添加 ~/.gemini/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Zed

添加 ~/.config/zed/settings.json:

{
  "context_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
      "env": {}
    }
  }
}

Install in Augment

添加到VS代码 settings.json 在...之下 augment.advanced:

{
  "augment.advanced": {
    "mcpServers": [
      {
        "id": "filesystem",
        "command": "npx",
        "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
      }
    ]
  }
}

Install in Roo Code

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

Install in Kilo Code

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
    }
  }
}

↑ 返回页首

用例

探索和理解代码库

发现项目结构并浏览不熟悉的存储库。从...开始 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和补丁工作流

比较文件版本并应用补丁。生成一个统一的差异 diff_files，预览 apply_patch(dryRun: true)，然后申请。支持单文件和多文件补丁（每个文件尽最大努力 results[]).

相关工具： diff_files, apply_patch

文件管理

创建目录、移动/重命名文件、删除文件，并通过SHA-256哈希验证文件完整性。

相关工具： mkdir, mv, rm, calculate_hash, write

建筑

[MCP Client]
    |
    | Transport: stdio (default) or Node Streamable HTTP (--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)
    |   +-- compare-files (original, modified)
    |   +-- analyze-path (path)
    |   +-- get-tool-help (name)
    |
    +-- 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 · find · tree · read · read_many · stat · stat_many · grep · mkdir · write · edit · mv · rm · calculate_hash · diff_files · apply_patch · search_and_replace

roots

列出允许的工作区根。首先调用——所有其他工具的作用域都在这些目录中。

_没有参数。_

______________________________________________________________________

ls

列出即时目录内容：名称、路径、类型、大小、修改日期。

______________________________________________________________________

find

按glob模式查找文件。返回具有元数据的匹配文件。

______________________________________________________________________

tree

使用有界递归渲染目录树。返回ASCII树+结构化JSON。

______________________________________________________________________

read

读取文本文件内容。使用 head/tail 预览大文件的前/后N行。

______________________________________________________________________

read_many

在一个请求中读取多个文本文件。

______________________________________________________________________

stat

获取文件/目录元数据：大小、已修改、权限、mime、tokenEstimate。

______________________________________________________________________

stat_many

在一个请求中获取多个文件/目录的元数据。

______________________________________________________________________

grep

搜索文件内容（类似grep）。返回具有可选上下文的匹配行。

______________________________________________________________________

mkdir

创建一个新目录（递归）。我暂时没有。

______________________________________________________________________

write

将内容写入文件， 覆盖所有现有内容。如果需要，创建父目录。

______________________________________________________________________

edit

应用连续的文字字符串替换（每次编辑第一次出现）。使用 dryRun 预览。

______________________________________________________________________

mv

移动或重命名文件或目录。

______________________________________________________________________

rm

永久删除文件或目录。 不可逆转。

______________________________________________________________________

calculate_hash

计算文件或目录的SHA-256哈希值。

______________________________________________________________________

diff_files

在两个文件之间生成统一的差异。输出直接馈入 apply_patch.

______________________________________________________________________

apply_patch

对一个或多个文件应用统一的差异补丁。单文件：失败时抛出。多文件：每个文件尽最大努力 results[].工作流程： diff_files -> apply_patch(dryRun) -> apply_patch.

______________________________________________________________________

search_and_replace

在与glob匹配的文件之间进行批量搜索和替换。替换 全部 每个文件的出现次数。总是 dryRun: true 第一。

资源

提示

MCP能力

工具注释

结构化输出

所有18个工具定义 outputSchema （Zod->JSON模式）并返回 structuredContent 旁边文字 content.Set FS_CONTEXT_STRIP_STRUCTURED=true 从工具定义中剥离输出模式（减少不使用结构化输出的LLM的令牌使用）。

↑ 返回页首

配置

HTTP和身份验证

文件大小限制

访问控制

输出和在线限制

任务

记录和诊断

演出

↑ 返回页首

HTTP端点

当开始时 --port ，服务器公开一个MCP端点：

所需标题：

• mcp-protocol-version --在初始化后的HTTP请求上使用协商的MCP协议版本
• mcp-session-id --需要 GET/DELETE （返回者 POST 初始化时）

身份验证： 对非环回HTTP绑定的请求需要 FILESYSTEM_MCP_API_KEY；然后客户必须发送 Authorization: Bearer 仅环回绑定可能会省略本地使用的身份验证。使用SHA-256定时安全比较。

CORS： 只允许本地主机来源(127.0.0.1, ::1, localhost).

主机验证： 环回HTTP绑定验证 Host 头球localhost, 127.0.0.1, [::1])以降低DNS重新绑定的风险。非环回绑定仍然需要 FILESYSTEM_MCP_API_KEY.

安全

↑ 返回页首

发展

• dev — tsc --watch --preserveWatchOutput --观看模式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 node-tests/**/*.test.ts --运行测试而不进行构建
• lint — eslint . --棉绒来源
• type-check — node scripts/tasks.mjs type-check --类型检查src+测试
• format — prettier --write . --格式代码
• inspector — npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder} --启动MCP检查器

构建与发布

• CI： .github/workflows/release.yml --在标记/发布之前运行lint、类型检查、测试、构建。
• Docker： 多阶段构建 node:24-alpine.Builder编译TypeScript+本机模块（re2）；发布阶段以非root身份运行 mcp 用户。
• npm： npm run prepublishOnly 运行lint+类型检查+构建。

故障排除

• “不允许使用目录” --至少传递一个目录参数或使用 --allow-cwd.
• 敏感文件被阻止 --与denylist匹配的文件(.env*, .gitSSH密钥）被设计阻止。检查 src/lib/constants.ts 查看完整列表。
• 大型结果外部化 --当工具输出超过内联限制时，它会作为资源缓存在 filesystem-mcp://result/{id}。读取资源URI以获取完整内容。
• Stdio：stdout上的日志 --仅在stderr上保留日志。服务器使用 console.error 用于诊断。
• HTTP 413 --请求正文超过 FS_CONTEXT_MAX_REQUEST_BYTES.增加限制或减小有效载荷大小。
• HTTP 401 — FILESYSTEM_MCP_API_KEY 已设置，但请求丢失或不正确 Authorization: Bearer 头球

学分

许可证

MIT许可证。看 许可证 了解详情。

↑ 返回页首