mcp_filesystem

yangjiacheng1996/mcp_filesystem

3.1

If you are the rightful owner of mcp_filesystem and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A stdio MCP server that controls system files and directories, allowing for operations such as copying and deleting files.

mcp_filesystem

一个可配置的MCP服务器，用于文件系统操作，支持stdio、streamable-http和SSE传输协议。

功能特性

  • 完整的文件系统操作（创建、读取、更新、删除文件和目录）
  • 跨平台支持（Windows、Linux、macOS）
  • 可配置的传输协议（stdio、streamable-http、SSE）
  • 无第三方依赖（仅使用Python标准库）
  • 深度适配uv工具，简化安装和使用

快速开始

安装uv

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装mcp-filesystem

# 使用uv直接从PyPI安装
uv tool install mcp-filesystem

# 或者从源码安装
git clone https://github.com/yangjiacheng1996/mcp_filesystem.git
cd mcp_filesystem
uv sync

使用方法

使用stdio传输协议（由MCP客户端自动管理）

stdio传输协议不需要手动启动服务器。MCP客户端（如Cherry Studio）会在需要时自动启动和管理服务器进程。

配置方式（在MCP客户端中配置）：

  • 类型: stdio
  • 命令: mcp-filesystem
  • 参数: --stdio
  • 举例：安装Chatbox，创建自定义MCP，填入命令：D:/mcp_filesystem/.venv/Scripts/mcp-filesystem --stdio

注意： 以下命令仅用于测试和调试目的，会启动一个前台进程占用命令行：

mcp-filesystem --stdio
使用streamable-http传输协议
mcp-filesystem --streamable-http --host 0.0.0.0 --port 8000
使用SSE传输协议
mcp-filesystem --sse --host 0.0.0.0 --port 8000

命令行参数说明

  • --config: 配置文件路径（默认：自动查找config.toml）
  • --stdio: 使用stdio传输协议
  • --streamable-http: 使用streamable-http传输协议
  • --sse: 使用SSE传输协议
  • --host: HTTP服务器主机地址（默认：从配置文件或0.0.0.0）
  • --port: HTTP服务器端口（默认：从配置文件或8000）

传输协议

1. stdio

  • 通过标准输入输出与MCP客户端通信
  • 适用于本地集成和命令行工具
  • 最简单的配置方式

2. streamable-http

3. SSE (Server-Sent Events)

在Cherry Studio中配置

对于stdio类型（推荐配置）:

  • 类型: stdio
  • 命令: mcp-filesystem
  • 参数: --stdio

注意： 这是正确的配置方式，Cherry Studio会在需要时自动启动和管理服务器进程，无需手动运行命令。

对于streamable-http类型:

对于SSE类型:

开发指南

从源码开发

# 克隆项目
git clone https://github.com/yangjiacheng1996/mcp_filesystem.git
cd mcp_filesystem

# 安装依赖
uv sync

# 运行测试
uv run test

# 运行开发服务器
uv run dev

可用脚本

  • uv run test: 运行测试套件
  • uv run test-cov: 运行测试并生成覆盖率报告
  • uv run dev: 启动开发服务器（stdio模式）

Python版本要求

当前支持 Python >= 3.11

项目结构

mcp_filesystem/
├── src/
│   └── mcp_filesystem/
│       ├── __init__.py          # 主程序入口
│       ├── system_information.py
│       ├── path_exist.py
│       ├── directory_*.py       # 各种目录操作模块
│       └── file_*.py           # 各种文件操作模块
├── tests/                       # 测试文件
├── docs/                       # 文档
├── pyproject.toml              # 项目配置
├── config.toml                 # 服务器配置
├── uv.lock                     # uv依赖锁文件
└── README.md                   # 项目说明

发布到PyPI

项目已配置为可发布到PyPI:

# 构建包
uv build

# 发布到PyPI
uv publish --token <你的PyPI账号token>

故障排除

常见问题

  1. 权限错误: 确保有足够的权限访问目标文件和目录
  2. 端口冲突: 如果端口被占用，尝试使用不同的端口号
  3. 依赖问题: 使用 uv sync 重新同步依赖

获取帮助

许可证

本项目采用 MIT 许可证 - 查看 文件了解详情。

贡献

欢迎贡献代码！请阅读贡献指南并提交Pull Request。

更新日志

v0.3.0

  • 添加SSE传输协议支持
  • 优化项目结构以支持PyPI打包
  • 深度适配uv工具
  • 更新文档和配置

v0.2.0

  • 初始版本发布
  • 支持stdio和streamable-http传输协议
  • 完整的文件系统操作功能