MCP Local Filesystem

mcp本地文件系统

一个最小的、安全第一的MCP（模型上下文协议）服务器，它允许Claude Desktop通过stdio直接读/写您的本地文件系统。没有HTTP服务器，没有开放端口，没有网络暴露。

为什么

创建文件的默认Claude Desktop工作流是手动的：

Claude generates file → you download it → you move it to your project directory

此MCP服务器消除了这种摩擦：

Claude generates file → MCP server writes it directly to disk

一个命令。零摩擦。文件准确地落在了它们所属的地方。

特性

• 7个文件系统工具 — write_file, read_file, list_directory, check_allowed, read_binary, write_binary, str_replace
• 路径沙盒 --所有操作都限制在明确允许的目录中
• 自动创建目录 — write_file 动态创建父目录
• 仅限stdio传输 --作为本地子进程运行，从不打开端口
• 占地面积最小 --空闲时内存低于30MB，启动时间低于500ms
• 零运行时依赖关系 超越 @modelcontextprotocol/sdk

快速开始

1.克隆和构建

git clone https://github.com/kmcallorum/mcp-local-filesystem.git
cd mcp-local-filesystem
npm install
npm run build

2.配置允许的目录

编辑 config.json 在项目根目录中：

{
  "allowedDirectories": [
    "/Users/yourname/Projects",
    "/Users/yourname/Development"
  ]
}

只有这些目录（及其子目录）中的路径是可访问的。其他一切都被拒绝了。

3.连接到克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "local-filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-local-filesystem/dist/index.js"]
    }
  }
}

替换 /absolute/path/to 使用克隆仓库的实际路径。

然后重新启动克劳德桌面 （完全退出并重新打开，而不仅仅是关闭窗口）。

重启后，您将在Claude的聊天输入区看到一个工具图标（锤子）。您的4个文件系统工具现在可用。

工具参考

write_file

将内容写入文件。自动创建父目录。覆盖现有文件而不提示。

成功响应：

{ "success": true, "path": "/Users/you/Projects/app/src/main.ts", "bytesWritten": 1234 }

错误响应：

{ "success": false, "error": "Access denied: path is outside allowed directories." }

read_file

读取文件的内容并将其作为字符串返回。

成功响应：

{ "success": true, "content": "file contents here...", "path": "/Users/you/Projects/app/README.md" }

list_directory

列出每个条目的目录内容及其元数据。

成功响应：

{
  "success": true,
  "path": "/Users/you/Projects/app",
  "entries": [
    { "name": "src", "type": "directory", "size": 128, "modified": "2026-03-09T10:30:00.000Z" },
    { "name": "package.json", "type": "file", "size": 542, "modified": "2026-03-09T09:15:00.000Z" }
  ]
}

check_allowed

检查路径是否在允许的目录内。不需要路径存在。永不出错，始终返回结果。

答复：

{ "allowed": true, "normalizedPath": "/Users/you/Projects/app/src/main.ts" }

read_binary / write_binary --对于二进制文件

对于任何需要字节精确保存的文件（pdf、docx、pptx、xlsx、， png、jpg、zip、编译/编码格式），使用 read_binary 和 write_binary.

这些工具通过JSON传输对文件内容进行base64编码，避免了 UTF-8可能会出现的损坏 read_file / write_file 在一个 二进制文件。

• read_binary --退货 content 作为base64字符串加 bytesRead
• write_binary --采用base64编码 content 字符串，解码和写入原始字节

对于纯文本文件（md、txt、json、ts、py、rego），请继续使用 read_file 和 write_file --它们更高效（没有base64开销）。

str_replace

替换单个、唯一的事件 old_str 和 new_str UTF-8格式 文本文件。使用此功能进行部分编辑——更改日期、固定线条、删除 a block——重写整个文件时使用 write_file 这将是浪费。

行为：

• 0个匹配项→ 错误： old_str not found in file
• 2+场比赛→ 匹配计数错误；添加周围上下文以消除歧义
• 正好1场比赛→ 替换并写回
• 非UTF-8（二进制）文件→ 拒绝并提示使用 write_binary

成功响应：

{
  "success": true,
  "path": "/Users/you/Projects/app/AGENTS.md",
  "matchLine": 2,
  "preview": "1: # AGENTS.md\n2: **Last Updated:** 2026-04-26\n3: \n4: body"
}

错误响应（不明确匹配）：

{ "success": false, "error": "old_str matches 3 times, must be unique. Add surrounding context to disambiguate." }

安全模型

安全是不可谈判的。每个文件系统操作在执行前都要经过路径验证。

配置参考

config.json

{
  "allowedDirectories": [
    "/absolute/path/one",
    "/absolute/path/two",
    "./relative/path/resolved/from/config/location"
  ]
}

Claude桌面配置

地点： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "local-filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-local-filesystem/dist/index.js"]
    }
  }
}

您可以并行运行多个MCP服务器——只需向中添加更多条目 mcpServers.

发展

npm run build        # Compile TypeScript → dist/
npm run dev          # Watch mode — recompiles on save
npm test             # Run all 44 tests
npm run inspector    # Launch MCP Inspector UI at http://localhost:6274

项目结构

src/
  index.ts                 # MCP server entry point, tool registration
  config.ts                # Config loading, path normalization, validation
  tools/
    write-file.ts          # write_file implementation
    read-file.ts           # read_file implementation
    list-directory.ts      # list_directory implementation
    check-allowed.ts       # check_allowed implementation
    read-binary.ts         # read_binary implementation (base64, byte-exact)
    write-binary.ts        # write_binary implementation (base64, byte-exact)
    str-replace.ts         # str_replace implementation (unique-match partial edit)
tests/
  config.test.ts           # 22 unit tests — config loading, path validation
  tools.test.ts            # 16 integration tests — all 4 text tools
  binary.test.ts           # 6 integration tests — binary round-trip
  str-replace.test.ts      # 8 integration tests — str_replace match/error cases
config.json                # Allowed directories configuration
dist/                      # Compiled output (git-ignored)

测试

测试包括：

• 路径验证 --允许的内部/外部目录、精确匹配、嵌套子目录， ../ 遍历攻击、前缀攻击(/ProjectsExtra 对比 /Projects)，空虚的对抗主义者
• 配置加载 --有效的配置、相对路径、丢失的文件、无效的JSON、丢失的键、错误的类型、空数组
• write_file --成功写入、自动mkdir、覆盖、路径拒绝
• read_file --现有文件、缺失文件、路径拒绝
• list_directory --包含元数据、缺少目录、路径拒绝的内容
• 允许检查 --允许/拒绝路径、不存在路径、规范化、从不抛出

故障排除

服务器无法启动

• 验证 config.json 存在于项目根目录中
• 检查它是否包含有效的JSON "allowedDirectories" 数组
• 跑 node dist/index.js 手动查看错误消息

“拒绝访问”错误

• 路径在中列出的目录之外 config.json
• 检查您允许的目录中的拼写错误
• 记住：路径是规范化的，所以 ../ 遍历允许的dirs将被捕获

工具未显示在Claude Desktop中

• 确保 claude_desktop_config.json 指向 dist/index.js （不是 src/index.ts)
• 跑 npm run build 确保 dist/ 存在
• 完全退出并重新打开Claude Desktop（而不仅仅是关闭窗口）
• 检查克劳德桌面日志： ~/Library/Logs/Claude/

配置更改未生效

• 重新启动Claude Desktop——配置仅在启动时加载

MCP调试检查员

跑 npm run inspector 启动MCP检查器UI。它以与Claude Desktop相同的方式连接到服务器，并允许您在以下位置手动调用每个工具 http://localhost:6274.

建筑

此服务器使用 模型上下文协议SDK 通过stdio传输。Claude Desktop将其作为子进程启动——没有守护进程，没有后台服务，没有端口绑定。

Claude Desktop
  └── spawns node dist/index.js (stdio)
        └── McpServer handles tool calls
              └── Path validation gate
                    └── Filesystem operation

服务器是无状态的。每个工具调用都会验证、执行和响应。没有缓存，没有观察者，没有后台任务。

许可证

麻省理工学院