Skip to main content
Glama
nutstore-mcp
by silverze

nutstore-mcp

坚果云网盘 MCP 服务,支持通过 AI 助手(OpenCode、Claude Desktop、Cursor 等)管理坚果云文件。

基于 WebDAV 协议实现,以本地 stdio 进程方式运行,文件上传/下载直接在你的本机与坚果云之间传输,支持任意格式文件(文本、图片、PDF、压缩包等)。

快速开始

第 1 步:安装 uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

第 2 步:获取坚果云应用密码

  1. 登录坚果云网页版

  2. 进入「账号」→「安全选项」→「第三方应用密码」

  3. 点击「添加应用密码」,记录生成的密码

第 3 步:配置 MCP 客户端

OpenCode

编辑 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "nutstore": {
      "type": "local",
      "command": ["uvx", "nutstore-mcp"],
      "enabled": true,
      "environment": {
        "NUTSTORE_USER": "your-email@example.com",
        "NUTSTORE_PASS": "your-app-password"
      }
    }
  }
}

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 或 %APPDATA%\Claude\claude_desktop_config.json(Windows):

{
  "mcpServers": {
    "nutstore": {
      "command": "uvx",
      "args": ["nutstore-mcp"],
      "env": {
        "NUTSTORE_USER": "your-email@example.com",
        "NUTSTORE_PASS": "your-app-password"
      }
    }
  }
}

Cursor

在 MCP 设置中添加:

{
  "mcpServers": {
    "nutstore": {
      "command": "uvx",
      "args": ["nutstore-mcp"],
      "env": {
        "NUTSTORE_USER": "your-email@example.com",
        "NUTSTORE_PASS": "your-app-password"
      }
    }
  }
}

企业私有部署(如 drive.company.com)额外添加:

"NUTSTORE_HOST": "https://drive.company.com/dav/"

Related MCP server: sync-vault-agent

环境变量

变量

说明

默认值

NUTSTORE_USER

坚果云账号(邮箱)

必填

NUTSTORE_PASS

第三方应用密码

必填

NUTSTORE_HOST

WebDAV 服务器地址

https://dav.jianguoyun.com/dav/

ROOT_PATH

根路径限制(限定操作范围)

/

READ_ONLY

只读模式

false

LOG_LEVEL

日志级别

WARNING


可用工具

目录与搜索

工具

说明

list_files

列出指定目录内容

search_files

按关键词搜索文件(支持递归)

get_directory_tree

获取目录树结构

文件信息

工具

说明

get_file_info

获取文件/目录详细信息

exists

检查路径是否存在

is_dir

判断路径是否为目录

check_connection

检查 WebDAV 连接状态

文本文件读写(AI 直接处理内容)

工具

说明

read_file_content

读取文本文件内容(.txt/.md/.json 等)

write_file_content

将文本内容写入远端文件

本地 ↔ 坚果云 文件传输(支持二进制/大文件)

工具

说明

download_file

从坚果云下载单个文件到本机

upload_file

从本机上传单个文件到坚果云

download_dir

从坚果云递归下载整个目录到本机

upload_dir

从本机递归上传整个目录到坚果云

文件管理

工具

说明

move_file

移动或重命名

copy_file

复制文件/目录

delete_file

删除文件或目录

batch_delete

批量删除(逗号分隔路径)

create_directory

创建目录

mkdirs

递归创建多级目录


对话示例

连接成功后,可直接用自然语言操作:

  • "列出坚果云/我的坚果云/下的所有文件"

  • "把坚果云上的 /文档/报告.pdf 下载到 ~/Downloads/"

  • "把本地 ~/项目/report.xlsx 上传到坚果云 /我的坚果云/工作/"

  • "搜索坚果云中包含'项目计划'的文件"

  • "在坚果云创建目录 /我的坚果云/2026/Q2"

  • "把坚果云 /我的坚果云/旧目录 整个下载到本地 /tmp/backup"


本地开发

git clone https://github.com/silverze/nutstore-mcp.git
cd nutstore-mcp

# 安装依赖
pip install -e ".[dev]"

# 复制并配置环境变量
cp .env.example .env
vim .env

# 直接运行
python -m app.main

发布到 PyPI

pip install hatch
hatch build
hatch publish

项目结构

nutstore-mcp/
├── app/
│   ├── __init__.py
│   ├── config.py        # 配置(从环境变量读取)
│   ├── webdav.py        # WebDAV 客户端封装
│   └── main.py          # FastMCP stdio 服务入口 + 所有工具定义
├── .env.example         # 环境变量模板
├── pyproject.toml       # 包元数据与入口点
├── requirements.txt     # 依赖列表
├── Dockerfile           # 可选:自托管 Docker 镜像
└── docker-compose.yml   # 可选:Docker Compose 配置

License

MIT

Available Tools

19 tools
batch_deleteA

批量删除坚果云中的文件/目录(逗号分隔多个路径)

Inputs: paths (required). Returns: result

check_connectionA

检查与坚果云 WebDAV 的连接状态

Inputs: no named parameters. Returns: result

copy_fileC

复制坚果云中的文件或目录

Inputs: dst_path (required), src_path (required). Returns: result

create_directoryC

在坚果云中创建新目录

Inputs: path (required). Returns: result

delete_fileB

删除坚果云中的文件或目录(谨慎使用!)

Inputs: path (required). Returns: result

download_dirA

从坚果云递归下载整个目录到本机本地路径(保留目录结构)。 local_dir 为本机目标目录路径,不存在时自动创建。

Inputs: local_dir (required), remote_dir (required). Returns: result

download_fileA

从坚果云下载单个文件到本机本地路径。 支持任意格式(文本、图片、PDF、压缩包等)。 local_path 为本机上的目标保存路径,例如 /home/user/docs/report.pdf

Inputs: local_path (required), remote_path (required). Returns: result

existsC

检查坚果云文件或目录是否存在

Inputs: path (required). Returns: result

get_directory_treeC

获取坚果云目录树结构

Inputs: path, max_depth. Returns: result

get_file_infoC

获取坚果云文件或目录的详细信息

Inputs: path (required). Returns: result

is_dirA

判断坚果云路径是否为目录

Inputs: path (required). Returns: result

list_filesA

列出坚果云指定目录下的文件和子目录

Inputs: path. Returns: result

mkdirsB

在坚果云中递归创建多级目录

Inputs: path (required). Returns: result

move_fileC

移动或重命名坚果云中的文件/目录

Inputs: dst_path (required), src_path (required). Returns: result

read_file_contentA

读取坚果云文本文件内容,返回文本供 AI 直接处理。 仅适合文本文件(.txt/.md/.json/.yaml 等),不支持二进制文件。 大文件请使用 download_file 下载到本地后处理。

Inputs: remote_path (required). Returns: result

search_filesC

在坚果云中搜索包含指定关键词的文件

Inputs: keyword (required), path, recursive. Returns: result

upload_dirA

将本机整个目录递归上传到坚果云(保留目录结构)。 local_dir 为本机已存在的目录路径。

Inputs: local_dir (required), remote_dir (required). Returns: result

upload_fileB

将本机单个文件上传到坚果云。 支持任意格式(文本、图片、PDF、压缩包等)。 local_path 为本机上已存在的文件路径,例如 /home/user/docs/report.pdf

Inputs: local_path (required), remote_path (required). Returns: result

write_file_contentA

将文本内容写入坚果云文件(新建或覆盖)。 仅适合文本内容,二进制文件请使用 upload_file。

Inputs: content (required), remote_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct operation: listing vs searching vs info vs existence; text vs binary I/O; single vs batch operations. Potential overlaps like list_files vs get_directory_tree or create_directory vs mkdirs are clarified by descriptions.

    Naming Consistency3/5

    Most tools follow a verb_noun pattern (list_files, upload_file, delete_file), but some diverge: 'exists' and 'is_dir' are bare predicates, 'mkdirs' is Unix-style, and 'batch_delete' uses an adverb prefix. The inconsistency is noticeable but not chaotic.

    Tool Count3/5

    With 19 tools, the set is on the heavy side for a file management server. Although each tool serves a specific purpose, some consolidation is possible (e.g., merge create_directory/mkdirs or handle batch in delete_file), pushing it beyond the typical well-scoped range.

    Completeness5/5

    The set covers the full lifecycle: create (mkdirs, write_file_content, upload_file), read (list_files, search_files, download_file), update (copy_file, move_file), and delete (delete_file, batch_delete), plus connectivity and info checks. No obvious gaps exist.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to search, read, and manage files across multiple cloud drives (Baidu, Aliyun, 115, OneDrive, Quark) through a unified interface.
      23 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes cloud drive file search, read/write, sharing, tagging, and more via the standardized MCP protocol, enabling AI clients like Claude Desktop and Cursor to interact with 一粒云 storage.
      -
    • A
      license
      B
      quality
      D
      maintenance
      This MCP server enables file management and local caching for Cloudreve v4 through OAuth authentication, allowing operations like listing, uploading, downloading, and sharing files via natural language in MCP-compatible clients.
      22
      1
      Apache 2.0