AI导哈

文件系统MCP服务器

一个提供安全文件读写操作的MCP服务器，适用于在沙盒目录中进行文件管理的开发场景。

  • by manju07
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 manju07/file-system-mcp-server

使用说明

文件系统MCP服务器

一种最小的模型上下文协议（MCP）服务器，在沙盒目录中提供安全的文件读写操作。此服务器旨在与MCP客户端配合使用，并包括一个用于交互式使用的Gradio web界面。

特性

此MCP服务器提供两个简单的工具：

  • read_file -从沙盒目录读取文件内容
  • write_file -将内容写入沙盒目录中的文件（如果文件不存在，则创建文件）

安全特性

  • 沙盒目录：所有文件操作仅限于 sandbox/ 目录
  • 路径解析：路径相对于沙盒自动解析，防止访问沙盒外的文件
  • 自动目录创建：写入文件时会自动创建父目录

安装

  1. 安装Python 3.8或更高版本

  2. 安装所需的依赖项：

pip install -r requirements.txt

主要依赖关系是：

  • openai-agents -OpenAI代理SDK（包括MCP支持）
  • openai -OpenAI SDK（用于Gemini API兼容性）
  • gradio -Web界面框架
  • python-dotenv -环境变量管理
  1. 安装MCP Python SDK：
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

或者，如果PyPI上有：

pip install mcp

配置

环境变量

创建一个 .env 项目根目录中的文件：

GOOGLE_API_KEY=your_google_api_key_here

从获取API密钥 谷歌人工智能工作室.

MCP客户端配置

要将此MCP服务器与MCP客户端（如Cursor）一起使用，请将其添加到MCP配置文件中。

对于光标，添加到MCP设置中（通常在 ~/.cursor/mcp.json 或类似）：

{
  "mcpServers": {
    "file-system": {
      "command": "python3",
      "args": ["/absolute/path/to/file-system-mcp-server/server.py"],
      "env": {}
    }
  }
}

或者，如果您已将其安装在虚拟环境中：

{
  "mcpServers": {
    "file-system": {
      "command": "/path/to/venv/bin/python",
      "args": ["/absolute/path/to/file-system-mcp-server/server.py"],
      "env": {}
    }
  }
}

看 example_config.json 作为参考配置。

用法

运行MCP服务器

服务器使用stdio（标准输入/输出）进行通信：

python server.py

使用Gradio Web界面

该项目包括一个Gradio web界面(app.py)它提供了一种将MCP服务器与谷歌的Gemini模型结合使用的交互式方式：

python app.py

这将：

  1. 启动web界面（通常在 http://127.0.0.1:7860)
  2. 连接到MCP服务器
  3. 使用Gemini 2.0 Flash模型处理自然语言提示
  4. 在沙盒目录中执行文件操作

该界面允许您输入如下提示：

  • “写一个关于机器人的故事”
  • “读取文件test.md”
  • “创建一个名为notes.txt的文件，其中包含一些内容”

工具使用示例

通过MCP客户端连接后，您可以使用以下工具：

读取文件：

{
  "name": "read_file",
  "arguments": {
    "path": "test.md"
  }
}

写入文件：

{
  "name": "write_file",
  "arguments": {
    "path": "hello.txt",
    "content": "Hello, World!"
  }
}

注意：所有路径都是相对于 sandbox/ 目录。如果沙箱目录不存在，服务器会自动创建沙箱目录。

项目结构

file-system-mcp-server/
├── server.py              # MCP server implementation
├── app.py                 # Gradio web interface
├── requirements.txt       # Python dependencies
├── example_config.json    # Example MCP client configuration
├── README.md             # This file
└── sandbox/              # Sandbox directory for file operations
    ├── hello.txt
    ├── sample.txt
    └── test.md

运作原理

MCP服务器(server.py)

  1. 初始化名为“基本文件服务器”的MCP服务器
  2. 创建一个 sandbox/ 安全文件操作目录
  3. 提供两个工具：
    • read_file：从沙盒目录读取文件
    • write_file：将文件写入沙盒目录
  4. 为了安全起见，所有路径都是相对于沙盒目录解析的

Gradio界面(app.py)

  1. 加载环境变量（包括 GOOGLE_API_KEY)
  2. 使用兼容OpenAI的API创建Gemini客户端
  3. 通过stdio连接到MCP服务器
  4. 使用OpenAI代理SDK创建具有MCP服务器访问权限的代理
  5. 处理自然语言提示并执行文件操作

安全说明

⚠️ 重要安全注意事项:

  • 所有文件操作仅限于 sandbox/ 目录
  • 绝对路径被净化以防止目录遍历
  • 如果沙盒目录不存在，则会自动创建它
  • 沙盒目录中的文件被排除在git之外（请参阅 .gitignore)

发展

测试

您可以直接测试服务器：

# Test reading a file
python -c "
import asyncio
from server import read_file_tool
result = asyncio.run(read_file_tool({'path': 'hello.txt'}))
print(result.content[0].text)
"

添加新工具

要添加新的文件操作，请修改 server.py:

  1. 创建新的异步函数（例如。， async def delete_file_tool(...))
  2. 将工具添加到 list_tools() 函数
  3. 在中添加处理程序 call_tool() 函数

为了安全起见，请记住将所有操作保存在沙盒目录中。

许可证

此项目按原样提供，用于模型上下文协议。

相关 MCP