# filesystem-mcp-server

**Repository Path**: yanxi-mcp/filesystem-mcp-server

## Basic Information

- **Project Name**: filesystem-mcp-server
- **Description**: filesystem-mcp-server
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# filesystem-mcp

基于官方 Python MCP SDK 的本地 stdio 文件系统服务。所有操作必须落在配置的绝对路径白名单目录中；未配置白名单时服务拒绝启动。

## 安装与启动

要求 Python 3.12 或 3.13。示例使用 Windows PowerShell：

```powershell
cd D:\python_workplace\filesystem-mcp
uv sync --extra dev
$env:FILESYSTEM_MCP_ALLOWED_ROOTS = 'D:\documents;D:\workspace\notes'
uv run filesystem-mcp
```

也可把 MCP 客户端的 `command` 指向 `D:\python_workplace\filesystem-mcp\.venv\Scripts\filesystem-mcp.exe`，并在客户端配置中设置环境变量。例如：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "D:\\python_workplace\\filesystem-mcp\\.venv\\Scripts\\filesystem-mcp.exe",
      "env": {
        "FILESYSTEM_MCP_ALLOWED_ROOTS": "D:\\documents"
      }
    }
  }
}
```

`FILESYSTEM_MCP_ALLOWED_ROOTS` 为必填项，支持多个已存在的绝对目录；分隔符采用操作系统路径分隔符（Windows 为 `;`，Unix 为 `:`）。不从当前工作目录隐式授权路径。可用 `FILESYSTEM_MCP_MAX_FILE_BYTES` 调整单文件上限，默认 10 MiB，必须为正整数。

## 工具

| 工具 | 用途 |
| --- | --- |
| `read_file` | 读取 UTF-8/GB18030 等文本，返回内容与编码 |
| `write_file` | 创建新 UTF-8 文件；拒绝覆盖 |
| `append_file` | 向已有 UTF-8 文件追加内容 |
| `search_file` | 按文件名通配符递归搜索 |
| `search_file_content` | 按不区分大小写的字面文本递归搜索 |
| `directory_browse` | 浏览单层目录 |
| `parse_pdf_file` | 提取 PDF 文本 |
| `parse_word_file` | 提取 DOCX 段落 |
| `parse_excel_file` | 提取 XLSX 单元格的缓存值 |

所有工具均要求绝对路径。搜索最多扫描 1000 个目录项、返回 100 条结果，并报告扫描或结果上限是否触及；目录浏览最多检查 1000 个条目。文本读取拒绝超过单文件上限的文件，并对小文件使用按修改时间与大小校验的 32 项缓存。搜索内容时跳过无法解码或过大的文件。PDF、DOCX、XLSX 解析还有页数、段落、行列、输出字符和展开大小上限；PDF 的单个解压流上限为 8 MiB。返回值包含截断标记。扫描版 PDF 不执行 OCR，旧 `.doc`/`.xls` 格式不在支持范围内。

## 写入授权与审计

默认只读。需要写入时，在启动服务前设置 `FILESYSTEM_MCP_ALLOW_WRITE=true`，且每次调用 `write_file` 或 `append_file` 时传入 `confirm_write=true`。调用方可以自行传入该标记；若需要真人逐次批准，应在 MCP 客户端启用工具审批。`write_file` 仅创建新文件；不会覆盖已有文件，也不会自动创建目录。追加操作要求目标文件为 UTF-8。不要将可写白名单配置为整个磁盘或用户主目录。

工具操作日志以 JSON 写入 stderr，记录时间、工具名、路径、状态与错误类型，不记录文件内容。服务只提供本地 stdio 传输；调用它的客户端应由可信用户启动。路径检查拒绝白名单外路径、符号链接、Windows junction 与备用数据流。并发外部进程修改同一路径时仍可能存在文件系统竞态，因此不要把服务暴露为不受信任用户共享的远程端点。

## 验证

```powershell
uv run pytest -q
uv run ruff check app tests
uv run ruff format --check app tests
```

## 目录

`app/filesystem/` 负责路径策略、读写、搜索和文档解析；`app/tools/` 负责 MCP 工具定义和审计；`app/main.py` 负责组装与启动。`tests/` 覆盖路径隔离、默认只读、写入授权、容量边界、解析和 MCP 客户端调用。