AI导哈

MCP文件系统服务器

一个基于Model Context Protocol（MCP）的安全文件系统服务器，提供对预定义目录的访问控制。

  • by gabrielmaialva33
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 gabrielmaialva33/mcp-filesystem

使用说明



Secure MCP Filesystem Server

A secure Model Context Protocol (MCP) server providing filesystem access within predefined directories


About   |    Technologies   |    Tools   |    Installation   |    Usage   |    License


：书签：关于

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


：计算机：技术


：扳手：工具


：package：安装

：heavy_check_mark： 先决条件

必须安装以下软件：


：arrowdown： 克隆存储库

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

：arrow_forward： 运行应用程序

地方发展

  # Install dependencies
  $ pnpm install

  # Build the application
  $ pnpm build

  # Run the server (specify directory to allow access to)
  $ pnpm start /path/to/allowed/directory

  # Or use configuration file
  $ pnpm start --config=config.json

使用NPM包

  # Install globally
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # Run the server
  $ mcp-filesystem /path/to/allowed/directory

  # Or use with npx (no installation needed)
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory

  # Create a sample configuration file
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

使用Docker

  # Build the Docker image
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # Run using Docker
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # Use with config file
  $ 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

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

：齿轮：用途

与Claude Desktop一起使用

Claude Desktop可以配置为使用此MCP服务器进行文件系统访问。将以下内容添加到您的 claude_desktop_config.json:

使用本地安装（推荐）

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

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

# Make the binary executable
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：读取文件内容
  • 读取多个文件：一次读取多个文件
  • write_file：创建或覆盖文件
  • edit_file：使用差异预览进行精确编辑
  • create_directory：递归创建目录
  • list_directory：列出目录内容
  • 目录树：获取递归树视图
  • move_file：移动或重命名文件
  • 搜索文件：查找与图案匹配的文件
  • 获取_文件_信息：获取文件元数据
  • list_allowed_directories：查看可访问的目录

系统和网络运营

  • get_metrics：查看服务器性能指标（v0.3.0+）
  • execute_命令：安全地执行系统命令（v0.3.1+）
  • curl_request：执行对外部API的HTTP请求（v1.2.0版本）

使用curl_request工具（v1.2.0版本）

这 curl_request 该工具将允许您向外部API发出HTTP请求：

// Example: Making a GET request with authentication
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// Example: POST request with JSON data
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 文件以获取更详细的示例。


：闪光：特征

核心功能

  • 安全访问：严格的路径验证可防止未经授权的访问
  • 文件操作：读取、写入、编辑和移动文件
  • 目录操作：创建、列出、获取树视图和搜索目录
  • 元数据访问：查看文件和目录信息
  • 命令执行：通过严格验证安全执行系统命令
  • 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
  }
}

：写作_和： 作者
加布里埃尔·马亚

许可证

MIT许可证

© 2024-present Maia

相关 MCP