<div align="center">

# 🔧 百度网盘 MCP Server 开发指南

**基于百度网盘开放 API 的 Model Context Protocol 服务器开发全攻略**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)

</div>

---

## 🎉 官方 MCP Server 已发布

> 百度网盘官方已发布 MCP Server，可直接使用！

| 项目 | 链接 |
|------|------|
| **GitHub 仓库** | [baidu-netdisk/mcp](https://github.com/baidu-netdisk/mcp) ⭐47 |
| **在线 SSE** | `https://mcp-pan.baidu.com/sse` |
| **文档** | [百度网盘 MCP 官方文档](https://pan.baidu.com/union/doc/) |

### 快速使用官方 MCP Server

**Claude Code：**
```bash
# 添加官方 SSE 服务器
claude mcp add --transport sse baidu-pan https://mcp-pan.baidu.com/sse
```

**OpenAI Codex** (`~/.codex/mcp_servers.json`)：
```json
{
  "mcpServers": {
    "baidu-pan": {
      "url": "https://mcp-pan.baidu.com/sse"
    }
  }
}
```

**本地 Stdio 模式**（支持上传）：
```bash
# 克隆官方仓库
git clone https://github.com/baidu-netdisk/mcp.git
cd baidu-pan-mcp

# 安装依赖
npm install

# 配置凭证
export BAIDU_APP_KEY=your_app_key
export BAIDU_SECRET_KEY=your_secret_key
export BAIDU_ACCESS_TOKEN=your_access_token

# 启动
npm start
```

官方 MCP Server 提供 **18 个 Tools**，覆盖文件列表、搜索、管理、上传和分享。

---

## 📖 本仓库内容

如果你想**自己开发**百度网盘 MCP Server，或深入了解 API 细节，本仓库提供完整的开发指南：

| 文档 | 内容 |
|------|------|
| [API 参考](docs/api-reference.md) | 百度网盘完整 REST API 文档，含所有端点、参数和响应 |
| [OAuth 授权指南](docs/oauth-guide.md) | OAuth 2.0 授权码流程详解，含自动授权脚本 |
| [MCP 开发指南](docs/mcp-dev-guide.md) | 从零开发 MCP Server 的完整教程 |
| [参考实现](src/index.ts) | TypeScript 参考代码（12 个 MCP Tools） |

---

## 🏗️ 自定义开发

### 为什么要自己开发？

- 🎯 需要定制化功能（如自动同步、批量操作）
- 🔧 需要特殊权限控制
- 📦 需要集成到已有系统
- 🧪 学习 MCP Server 开发

### 前置条件

| 依赖 | 说明 |
|------|------|
| 百度开放平台应用 | [openapi.baidu.com](https://openapi.baidu.com) 创建 |
| Node.js 18+ | 运行环境 |
| AI 编程助手 | Claude Code 或 OpenAI Codex |

### 安装

```bash
git clone https://github.com/XiLeForCLY/baidu-pan-mcp-server.git
cd baidu-pan-mcp-server
npm install
npm run build
```

### 配置凭证

```bash
export BAIDU_APP_KEY=your_app_key
export BAIDU_SECRET_KEY=your_secret_key
export BAIDU_ACCESS_TOKEN=your_access_token
```

### 获取 Access Token

使用项目提供的授权辅助脚本：

```bash
node scripts/oauth-helper.mjs
# 浏览器会自动打开，授权后终端显示 Token
```

详细流程参考 [OAuth 授权指南](docs/oauth-guide.md)。

### 注册到 AI 助手

```bash
# Claude Code
claude mcp add --transport stdio baidu-pan -- node dist/index.js

# Codex (在 ~/.codex/mcp_servers.json 中添加)
```

---

## 🛠️ MCP Tools 列表

| Tool | 功能 | 示例提示词 |
|------|------|-----------|
| `list_files` | 列出目录文件 | "列出网盘根目录的文件" |
| `search_files` | 搜索文件 | "搜索包含 report 的文件" |
| `get_file_info` | 获取文件详情 | "查看文件 ID 12345 的信息" |
| `download_file` | 获取下载链接 | "获取文件下载链接" |
| `create_folder` | 创建文件夹 | "创建文件夹 /项目备份" |
| `rename_file` | 重命名 | "把 old.txt 改名为 new.txt" |
| `move_files` | 移动文件 | "把 report.pdf 移到 /归档/" |
| `copy_files` | 复制文件 | "复制 config.json 到 /备份/" |
| `delete_files` | 删除文件 | "删除 /temp/ 下所有文件" |
| `get_user_info` | 用户信息 | "查看网盘账号信息" |
| `get_quota` | 存储配额 | "网盘还剩多少空间？" |
| `create_share` | 创建分享 | "分享 file.txt 提取码 1234" |

---

## 📐 架构图

```
┌─────────────────┐     MCP (stdio/SSE)  ┌──────────────────┐
│   AI 助手        │◄────────────────────►│  MCP Server      │
│ Claude Code /   │     JSON-RPC 2.0     │  (本项目)         │
│ Codex / Cursor  │                      │                  │
└─────────────────┘                      └────────┬─────────┘
                                                  │
                                                  │ REST API (HTTPS)
                                                  ▼
                                         ┌──────────────────┐
                                         │  百度网盘开放平台   │
                                         │ pan.baidu.com    │
                                         │ openapi.baidu.com│
                                         └──────────────────┘
```

---

## 📊 百度网盘 API 速查

| API | 端点 | 方法 |
|-----|------|------|
| 用户信息 | `/rest/2.0/xpan/nas?method=uinfo` | GET |
| 配额查询 | `/api/quota` | GET |
| 文件列表 | `/rest/2.0/xpan/file?method=list` | GET |
| 文件搜索 | `/rest/2.0/xpan/file?method=search` | GET |
| 文件元信息 | `/rest/2.0/xpan/multimedia?method=filemetas` | GET |
| 创建文件夹 | `/rest/2.0/xpan/file?method=create` | POST |
| 文件管理 | `/rest/2.0/xpan/file?method=filemanager` | POST |
| 秒传 | `/rest/2.0/xpan/file?method=rapidupload` | POST |
| 预上传 | `/rest/2.0/xpan/file?method=precreate` | POST |
| 上传分片 | `/rest/2.0/xpan/file?method=upload` | POST |
| 合并文件 | `/rest/2.0/xpan/file?method=create` | POST |
| 创建分享 | `/rest/2.0/xpan/share?method=rapidshare` | POST |

详细参数和响应请参考 [API 参考文档](docs/api-reference.md)。

---

## 🔗 相关资源

| 资源 | 链接 |
|------|------|
| 百度网盘官方 MCP | [baidu-netdisk/mcp](https://github.com/baidu-netdisk/mcp) |
| 百度网盘开放平台文档 | [pan.baidu.com/union/doc/](https://pan.baidu.com/union/doc/) |
| 百度开放平台 | [openapi.baidu.com](https://openapi.baidu.com) |
| MCP 协议规范 | [modelcontextprotocol.io](https://modelcontextprotocol.io) |
| MCP SDK (TypeScript) | [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) |
| bypy (Python 客户端) | [houtianze/bypy](https://github.com/houtianze/bypy) ⭐8.5k |

---

## 📄 License

MIT License © 2026