AI导哈

文件服务器

MCP File Server 是一个安全的沙盒文件服务器，通过模型控制协议（MCP）提供对文件系统操作的控制访问，支持在可配置的工作目录中读取、写入、列出、创建和删除文件和目录，并提供Git操作。

  • by undici77
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 undici77/MCPFileServer

使用说明

📂 MCP文件服务器

MCP文件服务器 是一个安全的沙盒文件服务器，通过 模型控制协议（MCP）。它支持在可配置的工作目录中读取、写入、列出、创建和删除文件和目录，同时执行严格的安全检查。Git操作也可用于工作目录中的存储库。

目录

🎯 特性

  • 沙盒操作 –所有路径都限制在用户指定的工作目录中。
  • 路径遍历保护、文件大小限制和阻止的扩展名。
  • 通过Base64编码提供二进制支持，用于安全传输非文本数据。
  • 工作目录中存储库的Git操作（状态、日志、分支、提交/推送/拉取）。
  • 适用于stdin/stdout集成的简单行分隔JSON-RPC协议。
  • 即用型 LM 工作室 通过最小 mcp.json 配置。

📦 安装和快速启动

# Clone the repository (if not already done)
git clone https://github.com/undici77/MCPFileServer.git
cd MCPFileServer

# Ensure git is installed on your system (required for git operations)
git --version

# Run the startup script – it creates a virtual environment,
# installs dependencies, and starts the server.
./run.sh -d /path/to/working/directory

脚本将：

  • 验证Python 3 可用。
  • 创建一个 .venv 虚拟环境（如果缺失）。
  • 安装所需的软件包(aiofiles).
  • 开始 main.py 使用提供的工作目录。

📌 Git操作注意事项：git操作使用Python的 subprocess 调用系统 git CLI。Git必须在PATH中安装并可用。

📌 提示： 确保脚本具有执行权限： chmod +x run.sh

⚙️ 命令行选项

选项 描述
-d, --directory 通往 工作目录。如果省略，服务器将使用当前进程目录。目录必须存在并且可读/写。

🤝 与LM集成 工作室

在项目中为文件服务器添加条目 mcp.json:

{
  "mcpServers": {
    "file-server": {
      "command": "/absolute/path/to/MCPFileServer/run.sh",
      "args": [
        "-d",
        "/absolute/path/to/working/directory"
      ],
      "env": {
        "WORKING_DIR": "."
      }
    }
  }
}
  • 将路径替换为机器上的绝对位置。
  • 确保 run.sh 可执行(chmod +x run.sh)并且安装了依赖项。

📡 MCP API概述

所有通信如下 JSON-RPC 2.0 通过stdin/stdout。

initialize

由客户端发送以获取服务器功能。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

服务器以协议版本、功能及其名称/版本进行响应。

tools/list

检索支持的工具的机器可读列表。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

响应包含一系列工具定义（名称、描述、输入模式）。

tools/call

调用特定工具。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { … }
  }
}

注： 工具名称的关键字是 **name**，不 tool。这与服务器实现相匹配。

🛠️ 可用工具

文件操作

工具 说明
read_file 读取文件的内容（文本或二进制）。
write_file 将文本或Base64编码的二进制数据写入文件。
list_files 列出具有可选筛选功能的文件和目录
create_directory 创建一个新的子目录（根据需要创建父目录）。
delete_file 删除单个文件。
delete_directory 删除目录；可选择强制删除非空树。
search_in_file 在文件中或目录中递归搜索字符串，返回上下文摘录。

read_file

读取工作目录中文件的内容。 参数

名称 类型 必填 描述
path string ✅ 目标文件的相对路径。
binary boolean ❌ （默认值： false) 设置为 true 将文件读取为二进制文件；结果是Base64编码。

示例

{
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "example.txt",
      "binary": false
    }
  }
}

write_file

将内容写入文件（如果需要，创建中间目录）。 参数

名称 类型 必填 描述
path string ✅ 目标文件的相对路径。
content string ✅ 要写入的文本或Base64编码的二进制数据 binary=true.
binary boolean ❌ （默认值： false) 设置为 true 对待 content 作为Base64编码的二进制文件。

示例

{
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "output.txt",
      "content": "Hello, world!",
      "binary": false
    }
  }
}

列表文件

列出工作目录下的文件和目录。 参数

名称 类型 必填 描述
extensions 字符串数组 ❌ 按文件扩展名过滤（例如。， [".py", ".txt"]).如果省略，则列出所有文件。
recursive boolean ❌ （默认值： true) 在以下情况下递归搜索子目录 true.
show_empty_dirs boolean ❌ （默认值： true) 包括不包含匹配文件的目录。

示例

{
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "extensions": [".py", ".txt"],
      "recursive": true,
      "show_empty_dirs": false
    }
  }
}

create_directory

创建一个新目录（包括任何缺失的父目录）。 参数

名称 类型 必填 描述
path string ✅ 要创建的目录的相对路径。

示例

{
  "method": "tools/call",
  "params": {
    "name": "create_directory",
    "arguments": { "path": "new_folder/subfolder" }
  }
}

删除文件

删除工作目录中的文件。 参数

名称 类型 必填 描述
path string ✅ 要删除的文件的相对路径。

示例

{
  "method": "tools/call",
  "params": {
    "name": "delete_file",
    "arguments": { "path": "temp.txt" }
  }
}

delete_directory

删除目录，可选择强制删除其内容。 参数

名称 类型 必填 描述
path string ✅ 要删除的目录的相对路径。
force boolean ❌ （默认值： false) 何时 true，递归删除非空目录。

示例

{
  "method": "tools/call",
  "params": {
    "name": "delete_directory",
    "arguments": { "path": "old_folder", "force": true }
  }
}

search_in_file

在文件中搜索字符串，或在目录中的所有文件中递归搜索字符串，返回上下文摘录。 参数

名称 类型 必填 描述
path string ✅ 文件的相对路径 或 目录。
search_string string ✅ 要搜索的文本。
context_lines 整数 ❌ （默认值： 3) 每场比赛前后要包含的行数。
case_sensitive boolean ❌ （默认值： false) 在以下情况下执行区分大小写的搜索 true.
max_matches 整数 ❌ （默认值： 50) 每个文件返回的最大匹配项数。

示例

{
  "method": "tools/call",
  "params": {
    "name": "search_in_file",
    "arguments": {
      "path": "log.txt",
      "search_string": "ERROR",
      "context_lines": 2,
      "case_sensitive": false,
      "max_matches": 10
    }
  }
}

Git操作

默认情况下，所有git操作都在工作目录上工作。要在嵌套存储库上操作，请使用 repo_path 参数。

工具 说明
git_status 显示工作树状态。
git_log 显示提交日志历史记录。
git_checkout 切换到其他分支或提交。
git_branch_create 创建一个新分支。
git_branch_delete 删除分支。
git_branch_list 列出存储库中的所有分支。
git_add 将文件内容添加到暂存区。
git_commit 将更改记录到存储库中。
git_push 将更改推送到远程存储库。
git_pull 从远程存储库获取并与之集成。
git_diff 显示提交、提交和工作树之间的变化。
git_clone 将存储库克隆到新目录中。
git_submodule_add 向存储库添加子模块。
git_submodule_update 更新现有子模块。
git_submodule_list 列出存储库中的所有子模块。

注： 所有git工具都支持可选 repo_path 用于在子目录中的存储库上操作的参数（例如。， "repo_path": "vendor/my-repo").如果省略，操作将直接针对工作目录。

git_status

显示工作树状态。 参数

名称 类型 必填 描述
short boolean ❌ （默认值： true) 使用短格式输出。
repo_path string ❌ 相对于工作目录的存储库路径（如果省略，则使用工作目录）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": { 
      "short": true,
      "repo_path": "vendor/my-repo"
    }
  }
}

git_log

显示提交日志历史记录。 参数

名称 类型 必填 描述
max_count 整数 ❌ （默认值： 20) 要显示的最大提交数。
oneline boolean ❌ （默认值： true) 显示紧凑的单行格式。
repo_path string ❌ 相对于工作目录的存储库路径（如果省略，则使用工作目录）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_log",
    "arguments": { 
      "max_count": 10, 
      "oneline": true,
      "repo_path": "vendor/my-repo"
    }
  }
}

git_checkout

切换到其他分支或提交。 参数

名称 类型 必填 描述
branch string ✅ 分支名称或提交哈希到签出。
repo_path string ❌ 相对于工作目录的存储库路径（如果省略，则使用工作目录）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_checkout",
    "arguments": { 
      "branch": "main",
      "repo_path": "vendor/my-repo"
    }
  }
}

git_branch_create

创建一个新分支。 参数

名称 类型 必填 描述
branch string ✅ 新分支的名称。
start_point string ❌ 新分支的起点（分支或提交）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_branch_create",
    "arguments": { 
      "branch": "feature/new-ui",
      "start_point": "main"
    }
  }
}

git_branch_delete

删除分支。 参数

名称 类型 必填 描述
branch string ✅ 要删除的分支的名称。
force boolean ❌ （默认值： false) 即使分支有未合并的更改，也要强制删除。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_branch_delete",
    "arguments": { 
      "branch": "old-branch",
      "force": true
    }
  }
}

git_branch_list

列出存储库中的所有分支。 参数

名称 类型 必填 描述
all boolean ❌ （默认值： false) 列出本地和远程分支。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_branch_list",
    "arguments": { "all": true }
  }
}

git_add

将文件内容添加到暂存区。 参数

名称 类型 必填 描述
paths 字符串数组 ✅ 要添加的文件路径列表。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_add",
    "arguments": { 
      "paths": ["src/main.py", "tests/test_main.py"] 
    }
  }
}

git_提交

将更改记录到存储库中。 参数

名称 类型 必填 描述
message string ✅ 提交消息。
all boolean ❌ （默认值： false) 自动暂存所有修改和删除的文件。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_commit",
    "arguments": { 
      "message": "Add new feature",
      "all": true
    }
  }
}

git_push

将更改推送到远程存储库。 参数

名称 类型 必填 描述
remote string ❌ （默认值： origin) 远程存储库名称。
branch string ❌ 要推送的分支（默认为当前分支）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_push",
    "arguments": { 
      "remote": "origin",
      "branch": "main"
    }
  }
}

git_pull

从远程存储库获取并与之集成。 参数

名称 类型 必填 描述
remote string ❌ （默认值： origin) 远程存储库名称。
branch string ❌ 要提取的分支（默认为当前分支）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_pull",
    "arguments": { 
      "remote": "origin",
      "branch": "main"
    }
  }
}

使用 git_diff

显示提交、提交和工作树之间的变化。 参数

名称 类型 必填 描述
path string ❌ 显示差异的特定文件或目录。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_diff",
    "arguments": {
      "path": "src/main.py"
    }
  }
}

git_clone

将存储库克隆到新目录中。 参数

名称 类型 必填 描述
url string ✅ 要克隆的存储库的URL（HTTPS或SSH）。
path string ✅ 将克隆存储库的目录名称（相对于工作目录）。
branch string ❌ 克隆后要结账的具体分支。
recursive boolean ❌ （默认值： false) 递归克隆子模块。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_clone",
    "arguments": {
      "url": "https://github.com/owner/repo.git",
      "path": "vendor/repo",
      "branch": "main"
    }
  }
}

git_submodule_add

向存储库添加子模块。 参数

名称 类型 必填 描述
url string ✅ 要添加为子模块的存储库的URL。
path string ✅ 放置子模块的路径。
name string ❌ 子模块的名称（可选，默认为路径）。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_submodule_add",
    "arguments": {
      "url": "https://github.com/owner/lib.git",
      "path": "vendor/lib"
    }
  }
}

git_submodule_update

更新现有子模块。 参数

名称 类型 必填 描述
init boolean ❌ （默认值： true) 更新前初始化子模块。
recursive boolean ❌ （默认值： true) 递归更新子模块。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_submodule_update",
    "arguments": {
      "init": true,
      "recursive": true
    }
  }
}

git_submodule_list

列出存储库中的所有子模块。 参数

名称 类型 必填 描述
summary boolean ❌ （默认值： true) 显示子模块状态摘要。

示例

{
  "method": "tools/call",
  "params": {
    "name": "git_submodule_list",
    "arguments": { "summary": true }
  }
}

🔐 安全功能

  • 路径遍历保护 –根据工作目录解析所有路径；试图逃逸会导致错误。
  • 阻止扩展名和敏感文件名 –文件，如 .exe, .bat, passwd等等，都被拒绝了。
  • 文件大小限制 –读/写超过 100 MiB (MAX_FILE_SIZE)被拒绝。
  • 空字节和危险模式检查 –防止格式错误的输入攻击。
  • Git命令验证 -验证分支名称和路径以防止注入攻击。

©2025 Undici77-保留所有权利。

相关 MCP