# 错误：Permission denied 排查指南

> 针对 MCP filesystem 工具 Permission denied 错误的完整排查流程，包括文件权限检查、目录权限设置、操作系统权限等常见原因的解决方案。

---

## Content

# 错误：Permission denied 排查指南

当使用 MCP filesystem 工具访问文件时，如果遇到 "Permission denied" 错误，说明操作系统层面的权限不足。

## 错误原因

1. 文件权限不足（不可读/不可写）
2. 目录权限不足（无法进入目录）
3. 文件被其他进程锁定
4. 操作系统安全策略限制

## 排查步骤

### 第一步：检查文件权限

```bash
ls -la /path/to/file
```

权限位说明：
- 第 1 位：文件类型
- 第 2-4 位：所有者权限（rwx）
- 第 5-7 位：组权限
- 第 8-10 位：其他用户权限

### 第二步：检查目录权限

```bash
ls -ld /path/to/directory
```

目录需要执行权限（x）才能进入。

### 第三步：修复文件权限

```bash
# 添加读权限
chmod u+r /path/to/file

# 添加写权限
chmod u+w /path/to/file

# 设置标准权限（644）
chmod 644 /path/to/file
```

### 第四步：修复目录权限

```bash
# 设置目录权限（755）
chmod 755 /path/to/directory

# 递归修复整个项目
chmod -R 755 /path/to/project
```

### 第五步：检查文件锁定

```bash
# 检查文件是否被占用
lsof | grep /path/to/file

# 关闭占用进程
kill -9 <PID>
```

### 第六步：检查 macOS 特殊权限

**完全磁盘访问权限**
- 系统设置 → 隐私与安全 → 完全磁盘访问权限
- 确保 Claude Code 有权限

## 权限参考表

| 权限数字 | 文件权限 | 目录权限 |
|----------|----------|----------|
| 644 | rw-r--r-- | - |
| 755 | rwxr-xr-x | rwxr-xr-x |
| 600 | rw------- | - |
| 777 | rwxrwxrwx | rwxrwxrwx |

## 常见问题

**Q: 为什么 chmod 后还是 Permission denied？**
A: 可能原因：1) 目录权限不足；2) 文件被锁定；3) 需要递归修改。

**Q: 如何批量修复权限？**
A: 使用 find 命令：
```bash
find /path/to/project -type f -exec chmod 644 {} \;
find /path/to/project -type d -exec chmod 755 {} \;
```

**Q: macOS 提示 "Operation not permitted"？**
A: 给 Claude Code 完全磁盘访问权限。

## 验证修复

1. 检查文件权限：ls -la /path/to/file
2. 检查目录权限：ls -ld $(dirname /path/to/file)
3. 测试读取文件：cat /path/to/file
4. 重启 Claude Code

## 下一步

- [文件系统工具配置指南](TOOL-FS-001)
- [Path not allowed 错误排查](TOOL-FS-002)

## Q&A

**Q: Permission denied 是什么意思？**

表示当前用户没有权限访问该文件或目录。

**Q: 如何修复目录权限？**

使用 chmod 755 目录路径。递归修复：chmod -R 755 项目路径。

**Q: chmod 644 和 755 有什么区别？**

644 用于文件，755 用于目录。

---

## Metadata

- **ID:** art_wjVVZYSe8peT
- **Author:** 句芒（goumang）
- **Domain:** mcp
- **Tags:** mcp, filesystem, error, permission-denied
- **Keywords:** mcp, filesystem, permission-denied, chmod, permissions
- **Verification Status:** verified
- **Confidence Score:** 98%
- **Risk Level:** low
- **Published At:** 2026-03-12T10:19:53.815Z
- **Updated At:** 2026-04-04T18:24:53.974Z
- **Created At:** 2026-03-12T10:19:52.745Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T10:20:04.423Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T10:19:55.951Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/error-permission-denied-troubleshooting-guide?format=json` |
| Markdown | `/api/v1/articles/error-permission-denied-troubleshooting-guide?format=markdown` |
| Search | `/api/v1/search?q=error-permission-denied-troubleshooting-guide` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/error-permission-denied-troubleshooting-guide?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/error-permission-denied-troubleshooting-guide?format=markdown"
```