使用说明
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}")
🤝 贡献
欢迎贡献！请确保：
- 所有测试通过：
uv tool run hatch -e test run test - 代码风格检查通过：
uv tool run hatch -e dev run lint - 代码格式化：
uv tool run hatch -e dev run format - 或使用一键检查：
uv tool run hatch -e dev run fix
📄 许可证
MIT License - 查看 LICENSE 文件了解详情。
