Guide: Setup mcp-server-filesystem Correctly

mcp-server-filesystem enables AI Agents to safely read/write local files. This guide covers configuration and security best practices.

What is filesystem tool?

Capabilities:

• read_file: Read file content
• write_file: Write to file
• list_directory: List directory contents
• search_files: Search files
• get_file_info: Get file information

Basic Configuration

Installation

# Using npx (recommended)
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

# Or global install
npm install -g @modelcontextprotocol/server-filesystem

Claude Code Config

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

allowedDirectories Details

Why Whitelist?

Security: Prevent AI from accessing sensitive files

• ❌ Do not open root /
• ❌ Do not open system dirs /etc, /usr
• ❌ Do not open home ~
• ✅ Only open project directories

Multiple Directories

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

Path Specifications

Must use absolute paths

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

Security Best Practices

1. Principle of Least Privilege

Only open necessary directories:

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

2. Separate Read/Write Permissions

Configure multiple filesystem instances:

{
  "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. Avoid Symlink Issues

Problem: Symlinks may point outside whitelist

Solution: Use real paths

realpath /path/to/symlink
readlink -f /path/to/symlink

Common Issues

Path not allowed

Cause: Directory not in allowedDirectories

Fix: Add directory to allowedDirectories

Permission denied

Cause: OS-level permission insufficient

Fix:

chmod 644 /path/to/file
chmod 755 /path/to/directory

Verify Configuration

1. Restart Claude Code
2. Type /mcp to see filesystem tools
3. Test reading a file

Next Steps

• Path not allowed Error
• Permission denied Error
• PostgreSQL Configuration