错误：Path not allowed 排查指南

当使用 MCP filesystem 工具访问文件时，如果遇到 "Path not allowed" 错误，说明访问的路径不在 allowedDirectories 白名单中。本文提供完整的排查和解决方案。

错误现象

Error: Path not allowed: /Users/username/some/path

错误原因

1. 路径不在 allowedDirectories 中
2. 使用了相对路径或 ~ 符号
3. 软链接指向白名单外的目录
4. 路径拼写错误

排查步骤

第一步：检查当前配置

查看 claude_desktop_config.json 中的 filesystem 配置，确认目标路径是否在白名单中。

第二步：检查路径格式

❌ 错误格式

• ~/Documents/project（使用了 ~）
• ./project（相对路径）
• ../other-project（使用了 ..）

✅ 正确格式

• /Users/username/project

第三步：检查软链接

# 检查是否为软链接
ls -la /path/to/check

# 获取真实路径
realpath /path/to/symlink

第四步：添加路径到白名单

编辑 claude_desktop_config.json，在 args 数组中添加新路径。

第五步：重启 Claude Code

修改配置后必须重启才能生效。

常见问题

Q: 为什么添加了路径还是报错？
A: 可能原因：1) 未重启 Claude Code；2) 路径格式错误；3) JSON 格式错误。

Q: 可以添加根目录吗？
A: 不推荐。添加根目录 / 会带来安全风险。

Q: 软链接会导致 Path not allowed 吗？
A: 会。如果软链接指向白名单外的目录，需要使用真实路径。

下一步

• Permission denied 错误排查
• 文件系统工具配置指南