WebDAV MCP Server

A Model Context Protocol (MCP) server that enables CRUD operations on a WebDAV endpoint with basic authentication. This server enables Claude Desktop and other MCP clients to interact with WebDAV file systems through natural language commands.

Features

• Connect to any WebDAV server with optional authentication

• Perform CRUD operations on files and directories

• Expose file operations as MCP resources and tools

• Run via stdio transport (for Claude Desktop integration) or HTTP/SSE transport

• Secure access with optional basic authentication

• Support for bcrypt-encrypted passwords for MCP server authentication (WebDAV passwords must be plain text due to protocol limitations)

• Connection pooling for better performance with WebDAV servers

• Configuration validation using Zod

• Structured logging for better troubleshooting

Prerequisites

• Node.js 18 or later

• npm or yarn

• WebDAV server (for actual file operations)

Installation

Option 1: Install from npm package

Option 2: Clone and build from source

Option 3: Docker

Configuration

Create a .env file in the root directory with the following variables:

Encrypted Passwords for MCP Server Authentication

For enhanced security of the MCP server (not WebDAV connections), you can use bcrypt-encrypted passwords instead of storing them in plain text:

1. Generate a bcrypt hash:

   # Using the built-in utility npm run generate-hash -- yourpassword # Or with npx npx webdav-mcp-generate-hash yourpassword

2. Add the hash to your .env file with the {bcrypt} prefix:

   AUTH_PASSWORD={bcrypt}$2y$10$CyLKnUwn9fqqKQFEbxpZFuE9mzWR/x8t6TE7.CgAN0oT8I/5jKJBy

This way, your MCP server password is stored securely. Note that WebDAV passwords must always be in plain text due to protocol requirements.

Usage

Running with stdio transport

This mode is ideal for direct integration with Claude Desktop.

Running with HTTP/SSE transport

This mode enables the server to be accessed over HTTP with Server-Sent Events for real-time communication.

Quick Start with Docker Compose

The easiest way to get started with both the WebDAV server and the MCP server is to use Docker Compose:

This setup uses hacdias/webdav, a simple and standalone WebDAV server written in Go. The configuration for the WebDAV server is stored in webdav_config.yml, which you can modify to adjust permissions, add users, or change other settings.

The WebDAV server stores all files in a Docker volume called webdav_data, which persists across container restarts.

WebDAV Server Configuration

The webdav_config.yml file configures the hacdias/webdav server used in the Docker Compose setup. Here's what you can customize:

For more advanced configuration options, refer to the hacdias/webdav documentation.

Testing

To run the tests:

Integrating with Claude Desktop

1. Ensure the MCP feature is enabled in Claude Desktop

Available MCP Resources

• webdav://{path}/list - List files in a directory

• webdav://{path}/content - Get file content

• webdav://{path}/info - Get file or directory information

Available MCP Tools

• webdav_create_remote_file - Create a new file on a remote WebDAV server

• webdav_get_remote_file - Retrieve content from a file stored on a remote WebDAV server

• webdav_update_remote_file - Update an existing file on a remote WebDAV server

• webdav_delete_remote_item - Delete a file or directory from a remote WebDAV server

• webdav_create_remote_directory - Create a new directory on a remote WebDAV server

• webdav_move_remote_item - Move or rename a file/directory on a remote WebDAV server

• webdav_copy_remote_item - Copy a file/directory to a new location on a remote WebDAV server

• webdav_list_remote_directory - List files and directories on a remote WebDAV server

Enhanced Features

• webdav_read_remote_file - Enhanced file reading with head/tail options

• webdav_edit_remote_file - Smart file editing with diff preview

• webdav_list_directory_with_sizes - Enhanced directory listing with sizes and sorting

• webdav_search_files - Search files using glob patterns with exclusion support

• webdav_get_directory_tree - Get recursive directory tree as JSON

• webdav_read_multiple_files - Read multiple files simultaneously

• webdav_get_file_info - Get detailed file/directory metadata

• webdav_range_request - Read specific byte range from a file (HTTP 206 Partial Content)

Available MCP Prompts

• webdav_create_remote_file - Prompt to create a new file on a remote WebDAV server

• webdav_get_remote_file - Prompt to retrieve content from a remote WebDAV file

• webdav_update_remote_file - Prompt to update a file on a remote WebDAV server

• webdav_delete_remote_item - Prompt to delete a file/directory from a remote WebDAV server

• webdav_list_remote_directory - Prompt to list directory contents on a remote WebDAV server

• webdav_create_remote_directory - Prompt to create a directory on a remote WebDAV server

• webdav_move_remote_item - Prompt to move/rename a file/directory on a remote WebDAV server

• webdav_copy_remote_item - Prompt to copy a file/directory on a remote WebDAV server

Example Queries in Claude

Here are some example queries you can use in Claude Desktop once the WebDAV MCP server is connected:

• "List files on my remote WebDAV server"

• "Create a new text file called notes.txt on my remote WebDAV server with the following content: Hello World"

• "Get the content of document.txt from my remote WebDAV server"

• "Update config.json on my remote WebDAV server with this new configuration"

• "Create a directory called projects on my remote WebDAV server"

• "Copy report.docx to a backup location on my remote WebDAV server"

• "Move the file old_name.txt to new_name.txt on my remote WebDAV server"

• "Delete temp.txt from my remote WebDAV server"

Enhanced Feature Operations

• "Read the first 20 lines of a log file: /logs/app.log"

• "Search for all JavaScript files: */.js, excluding node_modules directory"

• "Get the tree structure of the project directory"

• "List the contents of the uploads directory by file size"

• "Read multiple configuration files simultaneously"

• "Edit a configuration file with preview of changes"

• "Get detailed metadata information for a file"

• "Read the first 500 bytes of a file: bytes=0-499"

• "Read the last 100 bytes of a file: bytes=400-"

Programmatic Usage

You can also use this package programmatically in your own projects:

License

MIT

WebDAV MCP Server 增强功能文档

概述

本文档记录了对 WebDAV MCP Server 的全面增强功能，基于 filesystem MCP 服务器实现，大幅提升了文件操作能力和用户体验。

新增功能

1. 增强文件读取功能

webdav_read_remote_file

• 功能: 读取文件内容，支持 head/tail 参数

• 参数:

  • path (string): 文件路径

  • head (number, 可选): 返回文件的前 N 行

  • tail (number, 可选): 返回文件的后 N 行

• 特性:

  • 内存高效：大文件读取时不加载全部内容

  • 参数验证：head 和 tail 不能同时使用

  • 灵活读取：支持读取文件开头或结尾部分

2. 智能文件编辑功能

webdav_edit_remote_file

• 功能: 智能文件编辑，支持部分替换和 diff 预览

• 参数:

  • path (string): 文件路径

  • edits (array): 编辑操作数组，包含 oldText 和 newText

  • dryRun (boolean, 可选): 预览模式，生成 diff 但不实际修改文件

• 特性:

  • 精确匹配：查找并替换精确的文本序列

  • 多重编辑：支持单次操作中应用多个编辑

  • Diff 预览：生成 git 风格的差异预览

  • 安全模式：干运行模式确保编辑安全

3. 高级文件搜索功能

webdav_search_files

• 功能: 使用 glob 模式递归搜索文件和目录

• 参数:

  • path (string, 可选): 搜索起始目录，默认为根目录

  • pattern (string): Glob 模式匹配规则（如 *.txt, **/*.js, config.*）

  • excludePatterns (array, 可选): 排除模式数组

• 特性:

  • Glob 模式：支持标准的 glob 模式匹配

  • 排除模式：支持排除特定文件或目录

  • 递归搜索：深度搜索整个目录树

  • 路径验证：所有路径都经过安全验证

4. 目录树结构功能

webdav_get_directory_tree

• 功能: 获取递归目录树结构的 JSON 表示

• 参数:

  • path (string, 可选): 根目录路径，默认为根目录

  • excludePatterns (array, 可选): 排除模式数组

• 特性:

  • JSON 结构：返回结构化的 JSON 树数据

  • 递归遍历：完整遍历目录层次结构

  • 模式排除：支持排除特定项目

  • 清晰格式：2 空格缩进的可读格式

5. 增强目录列表功能

webdav_list_directory_with_sizes

• 功能: 增强目录列表，包含文件大小、排序和统计信息

• 参数:

  • path (string, 可选): 目录路径，默认为根目录

  • sortBy (enum, 可选): 排序方式（'name' 或 'size'），默认按名称排序

• 特性:

  • 文件大小：显示每个文件的格式化大小

  • 排序选项：支持按名称或大小排序

  • 统计信息：显示文件总数、目录总数和总大小

  • 格式化输出：清晰的表格格式显示

6. 详细文件信息功能

webdav_get_file_info

• 功能: 获取文件或目录的详细元数据

• 参数:

  • path (string): 文件或目录路径

• 特性:

  • 完整元数据：名称、路径、类型、大小、修改时间、MIME 类型

  • 格式化大小：人类可读的文件大小格式

  • 时间戳：详细的最后修改时间

  • 类型识别：区分文件和目录类型

7. 多文件同时读取功能

webdav_read_multiple_files

• 功能: 同时读取多个文件内容

• 参数:

  • paths (array): 文件路径数组

• 特性:

  • 并行处理：并发读取多个文件提高效率

  • 错误隔离：单个文件读取失败不影响其他文件

  • 格式化输出：清晰的分隔显示多个文件内容

  • 错误报告：详细的错误信息显示

8. 范围请求功能

webdav_range_request

• 功能: 按字节范围读取文件内容，支持 HTTP 206 Partial Content 响应

• 参数:

  • path (string): 文件路径

  • range (string): 字节范围，格式如 bytes=0-499, bytes=400-, 0-499

• 特性:

  • HTTP 标准兼容：完全兼容 HTTP 1.1 Range Requests 规范

  • 多种格式支持：支持 bytes=0-499, bytes=400-, 0-499 等格式

  • 大文件优化：适用于大文件的部分内容读取，减少网络传输

  • 元数据返回：返回 Content-Range, Content-Length, Total-Size 等信息

  • Unicode 支持：正确处理多字节字符的范围计算

技术实现

依赖项增强

• minimatch: 用于 glob 模式匹配的强大库

• TypeScript: 增强类型安全和代码质量

核心服务扩展

• WebDAVService: 新增多个方法支持高级功能

• 智能编辑: 内置 diff 生成和文本替换逻辑

• 搜索算法: 高效的递归搜索和模式匹配

错误处理

• 详细错误信息: 所有操作包含完整的错误描述

• 安全验证: 路径验证防止未授权访问

• 优雅降级: 部分失败不影响整体操作

使用示例

1. 读取文件前 10 行

2. 智能编辑文件

3. 搜索所有 JavaScript 文件

4. 获取目录树结构

5. 列出目录详情并按大小排序

6. 范围请求示例

性能优化

内存效率

• 流式读取: 大文件使用内存高效的流式处理

• 并发操作: 多文件操作使用并发处理

• 延迟加载: 按需加载文件内容和元数据

网络优化

• 连接池: 复用 WebDAV 连接减少开销

• 批量操作: 减少网络请求次数

• 错误重试: 自动处理临时网络问题

安全特性

路径验证

• 根目录限制: 所有操作限制在允许的目录内

• 符号链接处理: 安全处理符号链接防止路径遍历攻击

• 路径规范化: 统一路径格式防止绕过

操作安全

• 原子操作: 文件写入使用原子操作防止数据损坏

• 预览模式: 编辑操作支持预览避免误操作

• 详细日志: 所有操作记录详细日志

兼容性

向后兼容

• 现有 API: 保持所有现有工具和 API 不变

• 渐进增强: 新功能作为可选参数添加

• 默认行为: 保持原有默认行为不变

WebDAV 标准

• 协议兼容: 完全兼容 WebDAV 协议标准

• 多平台支持: 支持各种 WebDAV 服务器实现

• 认证支持: 保持现有认证机制

总结

这些增强功能大幅提升了 WebDAV MCP Server 的功能性和易用性，使其成为一个功能完整、性能优异、安全可靠的文件管理解决方案。新功能在保持向后兼容的同时，为用户提供了强大的文件操作能力，特别适合复杂的项目管理和开发工作流程。

🎯 范围请求功能

新增的范围请求功能是 WebDAV MCP Server 的一个重要里程碑，它提供了：

• HTTP 标准兼容: 完全兼容 HTTP 1.1 Range Requests 规范

• 性能优化: 大文件的部分内容读取，显著减少网络传输

• 应用场景丰富: 日志分析、音视频元数据提取、大文件预览等

• 技术先进: 精确的字节范围计算和 Unicode 字符支持

这一功能的加入，使 WebDAV MCP Server 在文件处理能力上达到了新的高度，为用户提供了更强大和灵活的文件操作体验。