指南：正确配置 mcp-server-filesystem

mcp-server-filesystem 让 AI Agent 能够安全地读写本地文件。本文详细讲解配置方法和安全最佳实践。

什么是 filesystem 工具？

filesystem 工具提供以下能力：

• read_file: 读取文件内容
• write_file: 写入文件
• list_directory: 列出目录内容
• search_files: 搜索文件
• get_file_info: 获取文件信息

基本配置

安装

# 使用 npx（推荐）
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

# 或全局安装
npm install -g @modelcontextprotocol/server-filesystem

Claude Code 配置

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents",
        "/Users/username/Projects"
      ]
    }
  }
}

allowedDirectories 详解

为什么需要白名单？

安全原因：防止 AI 意外访问敏感文件

• ❌ 不要开放根目录 /
• ❌ 不要开放系统目录 /etc, /usr
• ❌ 不要开放用户主目录 ~
• ✅ 只开放项目目录

配置多个目录

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/project-a",
        "/Users/username/project-b",
        "/Users/username/Downloads"
      ]
    }
  }
}

路径规范

必须使用绝对路径

✅ /Users/username/project
❌ ~/project
❌ ./project
❌ ../project

macOS/Linux

/Users/username/Documents/project
/home/username/project

Windows

C:\Users\username\Documents\project

安全最佳实践

1. 最小权限原则

只开放必要的目录：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/workspace/my-project"  // 只开放项目目录
      ]
    }
  }
}

2. 区分读写权限

如果需要更细粒度的控制，可以配置多个 filesystem 实例：

{
  "mcpServers": {
    "filesystem-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/readonly-data"
      ]
    },
    "filesystem-write": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/workspace"
      ]
    }
  }
}

3. 避免软链接问题

问题：软链接可能指向白名单外的目录

解决：使用真实路径

# 获取真实路径
realpath /path/to/symlink

# 或使用 readlink
readlink -f /path/to/symlink

常见问题

Path not allowed 错误

原因：访问的目录不在 allowedDirectories 中

解决：

1. 检查路径是否正确
2. 将目录添加到 allowedDirectories
3. 使用绝对路径

Permission denied 错误

原因：操作系统层面的权限不足

解决：

# 检查文件权限
ls -la /path/to/file

# 修改权限
chmod 644 /path/to/file
chmod 755 /path/to/directory

验证配置

1. 重启 Claude Code
2. 输入 /mcp 查看 filesystem 工具
3. 测试读取文件：

   请读取 /Users/username/project/README.md
   

下一步

• Path not allowed 错误排查
• Permission denied 错误排查
• PostgreSQL 工具配置