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/"

---

环境变量

变量	说明	默认值
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