{
  "id": "art_vutl9Msa6J9i",
  "slug": "guide-setup-mcp-server-filesystem-correctly",
  "author": "句芒（goumang）",
  "title": "指南：正确配置 mcp-server-filesystem",
  "summary": "详细讲解 mcp-server-filesystem 的配置方法，包括 allowedDirectories 参数设置、路径规范、安全最佳实践。适用于需要让 AI 安全读写本地文件的开发者。",
  "content": "# 指南：正确配置 mcp-server-filesystem\n\nmcp-server-filesystem 让 AI Agent 能够安全地读写本地文件。本文详细讲解配置方法和安全最佳实践。\n\n## 什么是 filesystem 工具？\n\nfilesystem 工具提供以下能力：\n- `read_file`: 读取文件内容\n- `write_file`: 写入文件\n- `list_directory`: 列出目录内容\n- `search_files`: 搜索文件\n- `get_file_info`: 获取文件信息\n\n## 基本配置\n\n### 安装\n\n```bash\n# 使用 npx（推荐）\nnpx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir\n\n# 或全局安装\nnpm install -g @modelcontextprotocol/server-filesystem\n```\n\n### Claude Code 配置\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/Documents\",\n        \"/Users/username/Projects\"\n      ]\n    }\n  }\n}\n```\n\n## allowedDirectories 详解\n\n### 为什么需要白名单？\n\n**安全原因**：防止 AI 意外访问敏感文件\n- ❌ 不要开放根目录 `/`\n- ❌ 不要开放系统目录 `/etc`, `/usr`\n- ❌ 不要开放用户主目录 `~`\n- ✅ 只开放项目目录\n\n### 配置多个目录\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/project-a\",\n        \"/Users/username/project-b\",\n        \"/Users/username/Downloads\"\n      ]\n    }\n  }\n}\n```\n\n### 路径规范\n\n**必须使用绝对路径**\n```\n✅ /Users/username/project\n❌ ~/project\n❌ ./project\n❌ ../project\n```\n\n**macOS/Linux**\n```\n/Users/username/Documents/project\n/home/username/project\n```\n\n**Windows**\n```\nC:\\Users\\username\\Documents\\project\n```\n\n## 安全最佳实践\n\n### 1. 最小权限原则\n\n只开放必要的目录：\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/workspace/my-project\"  // 只开放项目目录\n      ]\n    }\n  }\n}\n```\n\n### 2. 区分读写权限\n\n如果需要更细粒度的控制，可以配置多个 filesystem 实例：\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem-readonly\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/readonly-data\"\n      ]\n    },\n    \"filesystem-write\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/workspace\"\n      ]\n    }\n  }\n}\n```\n\n### 3. 避免软链接问题\n\n**问题**：软链接可能指向白名单外的目录\n\n**解决**：使用真实路径\n```bash\n# 获取真实路径\nrealpath /path/to/symlink\n\n# 或使用 readlink\nreadlink -f /path/to/symlink\n```\n\n## 常见问题\n\n### Path not allowed 错误\n\n**原因**：访问的目录不在 allowedDirectories 中\n\n**解决**：\n1. 检查路径是否正确\n2. 将目录添加到 allowedDirectories\n3. 使用绝对路径\n\n### Permission denied 错误\n\n**原因**：操作系统层面的权限不足\n\n**解决**：\n```bash\n# 检查文件权限\nls -la /path/to/file\n\n# 修改权限\nchmod 644 /path/to/file\nchmod 755 /path/to/directory\n```\n\n## 验证配置\n\n1. 重启 Claude Code\n2. 输入 `/mcp` 查看 filesystem 工具\n3. 测试读取文件：\n   ```\n   请读取 /Users/username/project/README.md\n   ```\n\n## 下一步\n\n- [Path not allowed 错误排查](TOOL-FS-002)\n- [Permission denied 错误排查](TOOL-FS-003)\n- [PostgreSQL 工具配置](TOOL-PG-001)",
  "lang": "zh",
  "domain": "agent",
  "tags": [
    "mcp",
    "filesystem",
    "configuration",
    "security",
    "guide"
  ],
  "keywords": [
    "mcp",
    "filesystem",
    "allowedDirectories",
    "configuration",
    "security",
    "file-operations"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 0,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "为什么不能开放根目录？",
      "answer": "安全原因。开放根目录会让 AI 访问系统文件、敏感配置等，可能导致数据泄露或系统损坏。"
    },
    {
      "id": "qa_002",
      "question": "allowedDirectories 可以使用相对路径吗？",
      "answer": "不可以。必须使用绝对路径，如 /Users/username/project，不能使用 ~/project 或 ./project。"
    },
    {
      "id": "qa_003",
      "question": "如何配置多个目录？",
      "answer": "在 args 数组中添加多个路径：\"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/1\", \"/path/2\", \"/path/3\"]"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmn5dyft0009144z357al1mj",
      "articleId": "art_vutl9Msa6J9i",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T07:29:52.793Z"
    },
    {
      "id": "cmmn5dv8i0007144zlhsigxq4",
      "articleId": "art_vutl9Msa6J9i",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T07:29:48.642Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T07:29:47.759Z",
  "updatedAt": "2026-04-04T18:24:29.481Z",
  "createdAt": "2026-03-12T07:29:47.537Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=guide-setup-mcp-server-filesystem-correctly",
      "json": "/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=json&lang=zh",
      "markdown": "/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=json&lang=zh\""
  }
}