# nutstore-mcp

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

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

## 快速开始

### 第 1 步：安装 uv

```bash
# 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`：

```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）：

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

#### Cursor

在 MCP 设置中添加：

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

> **企业私有部署**（如 `drive.company.com`）额外添加：
> ```json
> "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"

---

## 本地开发

```bash
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

```bash
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