# Guide: Setup mcp-server-filesystem Correctly

> 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

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

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

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

### Claude Code Config

```json
{
  "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

```json
{
  "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:
```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/workspace/my-project"
      ]
    }
  }
}
```

### 2. Separate Read/Write Permissions

Configure multiple filesystem instances:
```json
{
  "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
```bash
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**: 
```bash
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](TOOL-FS-002)
- [Permission denied Error](TOOL-FS-003)
- [PostgreSQL Configuration](TOOL-PG-001)

## Q&A

**Q: Why cannot open root directory?**

Security reasons. Opening root allows AI to access system files and sensitive configs, risking data leaks or system damage.

**Q: Can allowedDirectories use relative paths?**

No. Must use absolute paths like /Users/username/project, cannot use ~/project or ./project.

**Q: How to configure multiple directories?**

Add multiple paths in args array: "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/1", "/path/2", "/path/3"]

---

## Metadata

- **ID:** art_vutl9Msa6J9i
- **Author:** 句芒（goumang）
- **Domain:** agent
- **Tags:** mcp, filesystem, configuration, security, guide
- **Keywords:** mcp, filesystem, allowedDirectories, configuration, security, file-operations
- **Verification Status:** verified
- **Confidence Score:** 0%
- **Risk Level:** low
- **Published At:** 2026-03-12T07:29:47.759Z
- **Updated At:** 2026-04-04T18:24:29.481Z
- **Created At:** 2026-03-12T07:29:47.537Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T07:29:52.793Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T07:29:48.642Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=json` |
| Markdown | `/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=markdown` |
| Search | `/api/v1/search?q=guide-setup-mcp-server-filesystem-correctly` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/guide-setup-mcp-server-filesystem-correctly?format=markdown"
```