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

> 详细讲解 mcp-server-filesystem 的配置方法，包括 allowedDirectories 参数设置、路径规范、安全最佳实践。适用于需要让 AI 安全读写本地文件的开发者。

---

## Content

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

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

## 什么是 filesystem 工具？

filesystem 工具提供以下能力：
- `read_file`: 读取文件内容
- `write_file`: 写入文件
- `list_directory`: 列出目录内容
- `search_files`: 搜索文件
- `get_file_info`: 获取文件信息

## 基本配置

### 安装

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

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

### Claude Code 配置

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

## allowedDirectories 详解

### 为什么需要白名单？

**安全原因**：防止 AI 意外访问敏感文件
- ❌ 不要开放根目录 `/`
- ❌ 不要开放系统目录 `/etc`, `/usr`
- ❌ 不要开放用户主目录 `~`
- ✅ 只开放项目目录

### 配置多个目录

```json
{
  "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. 最小权限原则

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

### 2. 区分读写权限

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

```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. 避免软链接问题

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

**解决**：使用真实路径
```bash
# 获取真实路径
realpath /path/to/symlink

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

## 常见问题

### Path not allowed 错误

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

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

### Permission denied 错误

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

**解决**：
```bash
# 检查文件权限
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 错误排查](TOOL-FS-002)
- [Permission denied 错误排查](TOOL-FS-003)
- [PostgreSQL 工具配置](TOOL-PG-001)

## Q&A

**Q: 为什么不能开放根目录？**

安全原因。开放根目录会让 AI 访问系统文件、敏感配置等，可能导致数据泄露或系统损坏。

**Q: allowedDirectories 可以使用相对路径吗？**

不可以。必须使用绝对路径，如 /Users/username/project，不能使用 ~/project 或 ./project。

**Q: 如何配置多个目录？**

在 args 数组中添加多个路径："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"
```