MCP Filesystem Server

MCP Filesystem Server

一个基于 Model Context Protocol (MCP) 的文件系统服务器，使用 Python 和 FastMCP 实现。

🌟 特性

• 🔒 安全访问控制：只允许访问指定的目录
• 📁 完整文件操作：读取、写入、创建、移动、搜索文件
• 🛠️ 丰富的工具集：通过 MCP 协议提供9个文件系统工具
• 📊 资源管理：提供文件、目录和配置资源
• 🚀 多种启动方式：支持 stdio、HTTP、SSE 模式
• ✅ 测试驱动开发：完整的测试覆盖

🛠️ 安装

要求

• Python >= 3.10
• uv (推荐) 或 pip

从源码安装

# 克隆仓库
git clone <your-repo-url>
cd mcp_filesystem_server

# 使用 uv 安装（推荐）
uv sync

# 或使用 pip 安装
pip install -e .

🚀 使用方法

基本用法

# 默认 stdio 模式，使用当前目录
mcp-filesystem-server

# 指定允许访问的目录
mcp-filesystem-server --allowed-dir /path/to/folder --allowed-dir /another/path

# HTTP 模式
mcp-filesystem-server http --port 8080 --allowed-dir /home/user

# SSE 模式
mcp-filesystem-server sse --host 0.0.0.0 --port 3000 --allowed-dir /workspace

启动模式

模式	描述	用途
stdio	标准输入输出通信（默认）	与 MCP 客户端直接集成
http	HTTP 服务器	Web 应用集成
sse	Server-Sent Events	实时通信应用

命令选项

• --allowed-dir / -d: 允许访问的目录（可多次指定）
• --port / -p: 服务器端口（HTTP/SSE 模式）
• --host / -h: 服务器主机（HTTP/SSE 模式）

🔧 MCP 工具

服务器提供以下工具：

工具名称	功能	参数
read_file	读取文件内容	path: str
read_multiple_files	读取多个文件	paths: List[str]
read_image	读取图片文件	path: str, max_bytes?: int
read_multiple_images	读取多个图片文件	paths: List[str], max_bytes?: int
write_file	写入文件	path: str, content: str
create_directory	创建目录	path: str
list_directory	列出目录内容	path: str
move_file	移动/重命名文件	source: str, destination: str
search_files	搜索文件	path: str, pattern: str, exclude_patterns?: List[str]
get_file_info	获取文件信息	path: str
edit_file	编辑文件内容	path: str, edits: List[Dict], dry_run?: bool
get_filesystem_info	获取服务器配置信息	无

📊 MCP 资源

服务器提供以下资源：

资源URI	功能	描述
file://{path}	文件内容	以资源形式访问文件
directory://{path}	目录内容	JSON格式的目录列表
config://filesystem	服务器配置	服务器配置和能力信息

🧪 开发

安装开发依赖

# 安装 hatch 工具
uv tool install hatch

# 安装项目依赖
uv sync

运行测试

# 运行所有测试
uv tool run hatch run test

# 运行特定测试文件
uv tool run hatch run test -- tests/test_filesystem_service.py -v

# 运行测试并生成覆盖率报告
uv tool run hatch run coverage

代码格式化

# 格式化代码
uv tool run hatch run format

# 检查代码风格
uv tool run hatch run lint

# 类型检查
uv tool run hatch run typecheck

# 一键检查并修复
uv tool run hatch run fix

构建可执行文件

# 构建可执行文件
uv tool run hatch run all

项目结构

mcp_filesystem_server/
├── src/mcp_filesystem_server/
│   ├── __init__.py           # 包初始化
│   ├── version.py            # 版本信息
│   ├── filesystem_service.py # 核心文件系统服务
│   ├── server.py            # FastMCP 服务器实现
│   └── main.py              # CLI 入口点
├── tests/                   # 测试文件
│   ├── conftest.py          # pytest 配置
│   ├── test_filesystem_service.py
│   └── test_server.py
├── pyproject.toml           # 项目配置
└── README.md               # 项目文档

🔒 安全特性

• 路径限制：只能访问明确允许的目录
• 路径验证：防止目录遍历攻击
• 错误处理：安全的错误消息，不泄露系统信息
• 权限检查：每个操作都进行权限验证

📝 使用示例

与 Claude Desktop 集成

在 Claude Desktop 配置文件中添加：

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem-server",
      "args": ["--allowed-dir", "/your/workspace/path"]
    }
  }
}

与 MCP 客户端集成

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 创建服务器参数
server_params = StdioServerParameters(
    command="mcp-filesystem-server",
    args=["--allowed-dir", "/workspace"]
)

async def main():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 列出可用工具
            tools = await session.list_tools()
            print(f"可用工具: {[tool.name for tool in tools]}")
            
            # 调用工具
            result = await session.call_tool("read_file", {"path": "/workspace/test.txt"})
            print(f"文件内容: {result.content}")

🤝 贡献

欢迎贡献！请确保：

1. 所有测试通过：uv tool run hatch -e test run test
2. 代码风格检查通过：uv tool run hatch -e dev run lint
3. 代码格式化：uv tool run hatch -e dev run format
4. 或使用一键检查：uv tool run hatch -e dev run fix

📄 许可证

MIT License - 查看 LICENSE 文件了解详情。

🔗 相关链接

• Model Context Protocol
• MCP Python SDK
• MCP 规范