{
  "id": "art_vutl9Msa6J9i",
  "slug": "guide-setup-mcp-server-filesystem-correctly",
  "author": "句芒（goumang）",
  "title": "Guide: Setup mcp-server-filesystem Correctly",
  "summary": "Detailed guide on configuring mcp-server-filesystem, including allowedDirectories setup, path specifications, and security best practices. For developers who need AI to safely read/write local files.",
  "content": "# Guide: Setup mcp-server-filesystem Correctly\n\nmcp-server-filesystem enables AI Agents to safely read/write local files. This guide covers configuration and security best practices.\n\n## What is filesystem tool?\n\nCapabilities:\n- `read_file`: Read file content\n- `write_file`: Write to file\n- `list_directory`: List directory contents\n- `search_files`: Search files\n- `get_file_info`: Get file information\n\n## Basic Configuration\n\n### Installation\n\n```bash\n# Using npx (recommended)\nnpx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir\n\n# Or global install\nnpm install -g @modelcontextprotocol/server-filesystem\n```\n\n### Claude Code Config\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 Details\n\n### Why Whitelist?\n\n**Security**: Prevent AI from accessing sensitive files\n- ❌ Do not open root `/`\n- ❌ Do not open system dirs `/etc`, `/usr`\n- ❌ Do not open home `~`\n- ✅ Only open project directories\n\n### Multiple Directories\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### Path Specifications\n\n**Must use absolute paths**\n```\n✅ /Users/username/project\n❌ ~/project\n❌ ./project\n❌ ../project\n```\n\n## Security Best Practices\n\n### 1. Principle of Least Privilege\n\nOnly open necessary directories:\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. Separate Read/Write Permissions\n\nConfigure multiple filesystem instances:\n```json\n{\n  \"mcpServers\": {\n    \"filesystem-readonly\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/username/readonly-data\"]\n    },\n    \"filesystem-write\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/username/workspace\"]\n    }\n  }\n}\n```\n\n### 3. Avoid Symlink Issues\n\n**Problem**: Symlinks may point outside whitelist\n\n**Solution**: Use real paths\n```bash\nrealpath /path/to/symlink\nreadlink -f /path/to/symlink\n```\n\n## Common Issues\n\n### Path not allowed\n\n**Cause**: Directory not in allowedDirectories\n\n**Fix**: Add directory to allowedDirectories\n\n### Permission denied\n\n**Cause**: OS-level permission insufficient\n\n**Fix**: \n```bash\nchmod 644 /path/to/file\nchmod 755 /path/to/directory\n```\n\n## Verify Configuration\n\n1. Restart Claude Code\n2. Type `/mcp` to see filesystem tools\n3. Test reading a file\n\n## Next Steps\n\n- [Path not allowed Error](TOOL-FS-002)\n- [Permission denied Error](TOOL-FS-003)\n- [PostgreSQL Configuration](TOOL-PG-001)",
  "lang": "en",
  "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": "Why cannot open root directory?",
      "answer": "Security reasons. Opening root allows AI to access system files and sensitive configs, risking data leaks or system damage."
    },
    {
      "id": "qa_002",
      "question": "Can allowedDirectories use relative paths?",
      "answer": "No. Must use absolute paths like /Users/username/project, cannot use ~/project or ./project."
    },
    {
      "id": "qa_003",
      "question": "How to configure multiple directories?",
      "answer": "Add multiple paths in args array: \"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=en",
      "markdown": "/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=markdown&lang=en"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=json&lang=en\""
  }
}