mcp-文件系统

Name: mcp-文件系统
Author: gabrielmaialva33

作者：gabrielmaialva337 星标更新：2025-10-29

项目介绍

<h1 align="center"> <img src="https://raw.githubusercontent.com/gabrielmaialva33/mcp-filesystem/master/.github/assets/mcp.png" alt="MCP 文件系统" width="200"> 安全的 <a href="https://modelcontextprotocol.io/introduction">MCP</a> 文件系统服务器 </h1> 一个提供安全文件系统访问的模型上下文协议（MCP）服务器，仅限于预定义目录内 <img src="https://img.shields.io/github/license/gabrielmaialva33/mcp-filesystem?color=00b8d3?style=flat&logo=appveyor" alt="许可证" /> <img src="https://img.shields.io/github/languages/top/gabrielmaialva33/mcp-filesystem?style=flat&logo=appveyor" alt="GitHub 主要语言" > <img src="https://img.shields.io/github/languages/count/gabrielmaialva33/mcp-filesystem?style=flat&logo=appveyor" alt="GitHub 语言数量" > <img src="https://img.shields.io/github/repo-size/gabrielmaialva33/mcp-filesystem?style=flat&logo=appveyor" alt="仓库大小" > <a href="https://github.com/gabrielmaialva33/mcp-filesystem/commits/master"> <img src="https://img.shields.io/github/last-commit/gabrielmaialva33/mcp-filesystem?style=flat&logo=appveyor" alt="GitHub 最后一次提交" > <img src="https://img.shields.io/badge/made%20by-Maia-15c3d6?style=flat&logo=appveyor" alt="Maia" > </a> <a href="#bookmark-about">关于</a>   |    <a href="#computer-technologies">技术栈</a>   |    <a href="#wrench-tools">工具</a>   |    <a href="#package-installation">安装</a>   |    <a href="#gear-usage">使用</a>   |    <a href="#memo-license">许可证</a>

:bookmark: 关于

MCP 文件系统服务器通过模型上下文协议提供了对AI模型的安全文件系统访问。它强制执行严格的路径验证，并且只允许访问预定义的目录。

:computer: 技术栈

TypeScript
Node.js
MCP SDK
Zod
Docker
pnpm

:wrench: 工具

:package: 安装

:heavy_check_mark: 先决条件

必须安装以下软件：

Node.js (>=18.0.0)
Git
pnpm (>=8.0.0)
Docker (可选)
Docker Compose (可选)

:arrow_down: 克隆仓库

  $ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
  $ cd mcp-filesystem

:arrow_forward: 运行应用

本地开发

  # 安装依赖
  $ pnpm install

  # 构建应用
  $ pnpm build

  # 运行服务器（指定允许访问的目录）
  $ pnpm start /path/to/allowed/directory

  # 或使用配置文件
  $ pnpm start --config=config.json

使用NPM包

  # 全局安装
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # 运行服务器
  $ mcp-filesystem /path/to/allowed/directory

  # 或使用npx（无需安装）
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/
  allowed/directory

  # 创建样本配置文件
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

使用Docker

  # 构建Docker镜像
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # 使用Docker运行
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # 使用配置文件
  $ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json

使用Docker Compose

  # 创建数据目录
  $ mkdir -p data

  # 启动服务器
  $ docker-compose up -d

:gear: 使用

与Claude Desktop配合使用

Claude Desktop可以配置使用此MCP服务器进行文件系统访问。在你的claude_desktop_config.json中添加以下内容：

使用本地安装（推荐）

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": [
        "/Users/gabrielmaia/Documents",
        "/Users/gabrielmaia/Desktop",
        "/Users/gabrielmaia/Downloads"
      ]
    }
  }
}

确保全局可用可执行文件：

# 使二进制文件可执行
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem

使用NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@gabrielmaialva33/mcp-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

使用Docker

注意：当使用Docker时，默认情况下所有目录都必须挂载到/projects。添加ro标志会使目录变为只读。

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount",
        "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount",
        "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "gabrielmaialva33/mcp-filesystem",
        "/projects"
      ]
    }
  }
}

可用工具

MCP 文件系统服务器提供以下工具：

文件系统操作

read_file: 读取文件内容
read_multiple_files: 一次性读取多个文件
write_file: 创建或覆盖文件
edit_file: 使用差异预览进行精确编辑
create_directory: 递归创建目录
list_directory: 列出目录内容
directory_tree: 获取递归树视图
move_file: 移动或重命名文件
search_files: 查找匹配模式的文件
get_file_info: 获取文件元数据
list_allowed_directories: 查看可访问目录

系统及网络操作

get_metrics: 查看服务器性能指标（v0.3.0+）
execute_command: 安全地执行系统命令（v0.3.1+）
curl_request: 执行对外部API的HTTP请求（将在v1.2.0中提供）

使用curl_request工具（将在v1.2.0中提供）

curl_request工具将允许您对外部API执行HTTP请求：

// 示例：带有身份验证的GET请求
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// 示例：带有JSON数据的POST请求
curl_request({
  url: 'https://api.example.com/create',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  data: '{"name":"Example","value":123}',
})

请参阅docs/curl-tool-examples.md文件以获取更多详细示例。

:sparkles: 特性

核心特性

安全访问：严格的路径验证防止未经授权的访问
文件操作：读取、写入、编辑和移动文件
目录操作：创建、列出、获取树视图和搜索目录
元数据访问：查看文件和目录信息
命令执行：安全地执行系统命令并进行严格验证
Docker支持：使用Docker和Docker Compose轻松部署

v0.3.0新特性

结构化日志：不同级别的详细日志（调试、信息、警告、错误）
性能指标：跟踪操作计数、错误和执行时间
配置管理：支持JSON配置文件
路径缓存：提高频繁访问路径的性能
改进的错误处理：具有结构化信息的专用错误类型
文件大小验证：防止加载过大文件
CLI改进：帮助命令、版本信息和配置生成

配置选项

您可以使用以下命令创建配置文件：

$ mcp-filesystem --create-config=config.json

示例配置：

{
  "allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
  "logLevel": "info",
  "logFile": "/path/to/logs/mcp-filesystem.log",
  "serverName": "secure-filesystem-server",
  "serverVersion": "0.3.0",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 60000
  },
  "metrics": {
    "enabled": true,
    "reportIntervalMs": 60000
  },
  "security": {
    "maxFileSize": 10485760,
    "allowSymlinks": true,
    "validateRealPath": true
  }
}

:writing_hand: 作者


Gabriel Maia

许可证

MIT 许可证

<img src="https://raw.githubusercontent.com/gabrielmaialva33/gabrielmaialva33/master/assets/gray0_ctp_on_line.svg?sanitize=true" /> © 2024-present <a href="https://github.com/gabrielmaialva33/" target="_blank">Maia</a>