Local File Manager MCP Server

基于 FastMCP 构建的本地文件管理 MCP（Model Context Protocol）服务器。它赋予 AI 助手（如 Claude、Cursor、WorkBuddy 等）安全地读取、写入、追加、搜索和列出本地文件系统中文件的能力。

---

目录

• 项目架构
• 功能特性
• 环境准备
• 快速开始
• 工具 API 参考
• 客户端集成指南
• 安全性说明
• 开发与测试
• CI/CD 流程

---

项目架构

mcp/
├── server.py           # MCP 服务器主入口，定义所有工具
├── requirements.txt    # Python 依赖
├── README.md           # 项目文档
└── .github/
    └── workflows/
        ├── ci.yml      # CI 工作流（Push/PR 触发自动测试）
        └── release.yml # Release 工作流（Tag 触发自动发布）

核心设计

AI 客户端（Claude / Cursor / WorkBuddy）
        │  MCP Protocol (stdio / SSE)
        ▼
┌──────────────────────────────┐
│       FastMCP Server         │
│  ┌────────────────────────┐  │
│  │  工具层 (Tools Layer)  │  │
│  │  • list_files          │  │
│  │  • read_file           │  │
│  │  • write_file          │  │
│  │  • append_to_file      │  │
│  │  • search_files        │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │  安全层 (get_safe_path) │  │
│  └────────────────────────┘  │
└──────────────────────────────┘
        │
        ▼
   本地文件系统

• 传输协议：默认使用 stdio（标准输入输出），兼容所有主流 MCP 客户端
• 安全机制：get_safe_path() 对所有路径进行标准化处理，防止路径遍历攻击
• 依赖极简：仅依赖 mcp>=1.0.0，部署简单

---

功能特性

工具	说明
list_files	列出目录内容，区分文件与子目录
read_file	读取文本文件内容（UTF-8），自动检测二进制文件
write_file	创建或覆盖文件，可控制是否覆盖
append_to_file	向已有文件追加内容
search_files	支持 glob 模式（含 ** 递归）的文件搜索

---

环境准备

• Python 3.10 或更高版本
• pip 包管理器

# 克隆仓库
git clone https://github.com/PanNinan/mcp.git
cd mcp

# 安装依赖
pip install -r requirements.txt

---

快速开始

方式一：直接运行（调试用）

python server.py

服务器启动后将监听 stdio，可通过任何 MCP 兼容客户端连接。

方式二：注册到 Claude Code

mcp add file-manager python /path/to/mcp/server.py

方式三：注册到 Cursor

在 Cursor 的 MCP 配置（~/.cursor/mcp.json）中添加：

{
  "mcpServers": {
    "file-manager": {
      "command": "python",
      "args": ["/path/to/mcp/server.py"]
    }
  }
}

方式四：注册到 WorkBuddy

在 WorkBuddy 的 MCP 配置（~/.workbuddy/mcp.json）中添加：

{
  "mcpServers": {
    "file-manager": {
      "command": "python",
      "args": ["E:/code/mcp/server.py"]
    }
  }
}

方式五：使用 uv（推荐，无需手动 pip 安装）

uvx --from . mcp-file-manager

---

工具 API 参考

list_files(directory_path)

列出指定目录下的所有文件和子目录。

参数	类型	默认值	说明
directory_path	str	"."	目标目录路径（绝对或相对路径）

返回值：list[str]，每项格式为 [DIR] name 或 [FILE] name

示例：

list_files("C:/Users/admin/Documents")
# 返回: ["[DIR]  Projects", "[FILE] notes.txt", ...]

list_files(".")
# 返回基础目录的内容

---

read_file(file_path)

读取指定文件的文本内容。

参数	类型	说明
file_path	str	文件路径（绝对或相对路径）

返回值：str，文件内容；若为二进制文件或不存在则返回错误信息

示例：

read_file("README.md")
read_file("C:/Users/admin/config.json")

---

write_file(file_path, content, overwrite)

将内容写入文件，若文件不存在则创建（含中间目录）。

参数	类型	默认值	说明
file_path	str	—	目标文件路径
content	str	—	要写入的内容
overwrite	bool	False	是否允许覆盖已存在文件

示例：

write_file("output/result.txt", "Hello, World!")
write_file("config.json", '{"key": "value"}', overwrite=True)

---

append_to_file(file_path, content)

向已存在的文件末尾追加内容。

参数	类型	说明
file_path	str	目标文件路径
content	str	要追加的内容

示例：

append_to_file("log.txt", "\n2026-04-15 操作完成")

---

search_files(pattern, directory)

使用 glob 模式在指定目录中搜索文件。

参数	类型	默认值	说明
pattern	str	—	glob 匹配模式
directory	str	"."	搜索起始目录

常用模式：

模式	说明
*.txt	当前目录所有 .txt 文件
**/*.py	递归搜索所有 .py 文件
data_*.csv	匹配以 data_ 开头的 CSV 文件
**/*.{json,yaml}	递归搜索 JSON 和 YAML 文件

示例：

search_files("**/*.py", "C:/Projects/myapp")
search_files("*.log", "/var/logs")

---

客户端集成指南

与 Claude Desktop 集成

编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）或
~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "file-manager": {
      "command": "python",
      "args": ["E:/code/mcp/server.py"]
    }
  }
}

重启 Claude Desktop 后，在对话中即可使用文件操作工具。

---

安全性说明

1. 路径处理：所有路径经过 os.path.abspath() 标准化，消除 ../ 等路径遍历风险
2. 二进制保护：read_file 自动检测二进制文件，拒绝读取并提示
3. 写入保护：write_file 默认不覆盖已有文件（需显式设置 overwrite=True）
4. 编码统一：所有文件操作强制使用 UTF-8 编码

⚠️ 注意：服务器对所有可访问绝对路径均有读写权限。建议在受信任的环境中运行，或根据业务需求在 get_safe_path() 中添加白名单目录限制。

---

开发与测试

本地运行测试

# 安装测试依赖
pip install pytest pytest-asyncio

# 运行所有测试
pytest tests/ -v

# 运行并查看覆盖率
pip install pytest-cov
pytest tests/ --cov=server --cov-report=term-missing

代码风格检查

pip install flake8
flake8 server.py --max-line-length=120

手动连接测试

使用 MCP Inspector 快速验证服务器：

npx @modelcontextprotocol/inspector python server.py

---

CI/CD 流程

本项目使用 GitHub Actions 实现自动化流程：

CI 工作流（ci.yml）

触发条件：每次 Push 或 Pull Request 到 main / develop 分支

执行步骤：

1. 检出代码
2. 配置 Python 3.10 / 3.11 / 3.12 矩阵环境
3. 安装依赖
4. 代码风格检查（flake8）
5. 运行测试（pytest）

Release 工作流（release.yml）

触发条件：推送格式为 v*.*.* 的 Git Tag（如 v1.0.0）

执行步骤：

1. 运行完整测试套件
2. 自动创建 GitHub Release
3. 上传源码包作为 Release Asset

发布新版本：

git tag v1.0.0
git push origin v1.0.0

---

License

MIT