MCP Filesystem Server

Created By

Spark-Liang7 months ago

Overview Content Tools Comments

Content

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}")