115 MCP Server
面向 115 网盘的 MCP 服务器,基于 FastMCP 与 p115client,提供完整的文件、离线下载、分享与媒体库管理能力。 / A full-featured MCP server for 115 Cloud, built on FastMCP and p115client, with file, offline download, sharing, and media library management capabilities.
Ask AI about 115 MCP Server
Powered by Claude · Grounded in docs
I know everything about 115 MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
115-MCP-Server
基于 FastMCP 和 p115client 的 115 网盘 MCP 服务器。
项目来源与致谢
本项目是一个基于以下开源项目进行封装与扩展的 MCP 服务器:
- p115client:115 网盘 Python 客户端与接口封装
- FastMCP:用于快速构建 MCP 服务器的 Python 框架
本项目的大部分 115 能力都封装自 p115client 提供的客户端与文件系统接口,在此对原项目作者与贡献者表示感谢。
同时也感谢 FastMCP 提供了稳定、清晰的 MCP 服务构建能力,使这些 115 功能可以以 MCP 工具的形式对外提供。
快速开始
如果你想最快跑起来,可以按这个顺序:
- 创建虚拟环境
- 安装依赖
- 配置
P115_COOKIES或P115_COOKIES_PATH - 启动 MCP 服务
- 在 MCP 客户端里接入
最简命令:
python -m venv .venv
./.venv/Scripts/python -m pip install -e .
./.venv/Scripts/115-MCP-Server
功能
- 查询认证状态
- 列出目录与读取元数据
- 搜索文件/目录
- 创建目录
- 上传本地文件到 115
- 下载 115 文件到本地
- 移动、复制、重命名、删除文件或目录
- 批量移动、批量复制、批量删除
- 获取文件下载直链
- 查询空间信息
- 将目录路径解析为目录 ID
- 判断文件是否存在、统计目录数量、获取祖先链
- 按 glob 匹配文件、递归遍历目录、获取 stat 信息
- 离线下载任务创建、查询、清理、删除、BT 信息查询
- 离线下载默认目录查询/设置、任务重启、任务计数
- 离线任务高级筛选、批量删除、sign 信息、详细套餐/配额查询
- 回收站列表、详情、恢复
- 回收站清空或永久删除指定回收站条目
- 标签列表与标签设置
- 分享列表、分享详情、接收码、接收分享、分享下载链接、访问用户、分享下载配额
- 查询账号信息与索引首页统计
- 支持通过 MCP 发起二维码登录并保存 cookies
安装
环境要求
- Python 3.12 或更高版本
- Windows 环境已验证可用
- 需要能访问 115 相关接口
方式一:源码安装(推荐)
python -m venv .venv
./.venv/Scripts/python -m pip install --upgrade pip
./.venv/Scripts/python -m pip install -e .
安装完成后,可执行入口包括:
./.venv/Scripts/115-MCP-Serverpython -m mcp_115_server(内部模块入口)
方式二:开发模式重新安装
如果你修改了源码并希望重新安装当前项目:
./.venv/Scripts/python -m pip install -e .
验证安装是否成功
./.venv/Scripts/115-MCP-Server --help
如果能看到命令行帮助,说明安装成功。
配置
认证方式
本项目支持三种认证方式:
- 直接传入环境变量
P115_COOKIES - 通过环境变量
P115_COOKIES_PATH指向 cookies 文件 - 通过 MCP 工具执行二维码登录
本项目不支持通过项目根目录
.env文件自动加载配置。配置来源只保留两种:运行进程时注入的环境变量,以及P115_COOKIES_PATH指向的本地.txtcookies 文件。
推荐使用环境变量 + .txt cookies 文件:
P115_COOKIES_PATH=~/115-cookies.txt
P115_CHECK_FOR_RELOGIN=true
P115_ALLOW_QRCODE_LOGIN=false
P115_CONSOLE_QRCODE=false
也支持直接通过环境变量传入 cookies:
P115_COOKIES=UID=...; CID=...; SEID=...; KID=...
说明:
-
P115_COOKIES优先级高于P115_COOKIES_PATH -
P115_COOKIES_PATH应指向本机上的.txtcookies 文件,例如115-cookies.txt -
未配置 cookies 时,默认不会触发扫码登录
-
若要允许
p115client在需要时尝试扫码登录,请设置P115_ALLOW_QRCODE_LOGIN=true -
Cookie 平台自动推断
服务默认依赖 p115client 根据 cookie 自动推断首选登录平台。
当前行为:
- 不需要手动配置 cookie 平台。
- 服务会优先使用
P115Client从 cookie 推断出的平台。 - 如果某个接口在当前平台下失败,服务只做最小必要的接口级回退,而不会对大量平台进行轮询。
- 这样可以减少失败请求数量,降低触发风控的风险。
推荐的环境变量写法
P115_COOKIES_PATH=C:\Users\your-name\115-cookies.txt
P115_CHECK_FOR_RELOGIN=true
P115_ALLOW_QRCODE_LOGIN=false
P115_CONSOLE_QRCODE=false
FASTMCP_TRANSPORT=stdio
这些变量应通过以下任一方式提供:
- MCP 客户端配置中的
environment - 当前终端 / 系统环境变量
- 进程启动器(如 OpenCode、Claude Desktop、Cursor 等)的环境注入
不要把配置写到项目根目录 .env 中;服务不会读取它。
启动
stdio
适用于绝大多数 MCP 桌面客户端。
./.venv/Scripts/115-MCP-Server
HTTP
适用于需要通过 URL 接入 MCP 的客户端或调试场景。
./.venv/Scripts/115-MCP-Server --transport http --host 127.0.0.1 --port 8000 --path /mcp
也可以使用安装后的命令:
115-MCP-Server
Windows 也可以直接运行脚本:
powershell -ExecutionPolicy Bypass -File .\scripts\run-stdio.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\run-http.ps1
或:
scripts\run-stdio.cmd
scripts\run-http.cmd
启动参数说明
--transport:stdio/http/streamable-http/sse--host:HTTP 监听地址--port:HTTP 监听端口--path:HTTP MCP 路径--log-level:日志级别
例如:
./.venv/Scripts/115-MCP-Server --transport http --host 127.0.0.1 --port 8010 --path /mcp --log-level debug
MCP 客户端接入示例
在开始之前,先准备这几个信息:
- Python 可执行文件:
C:\Users\flami\Downloads\115-MCP\.venv\Scripts\python.exe - 备用模块入口:
python -m mcp_115_server - 推荐环境变量:
P115_COOKIES_PATH=C:\Users\your-name\115-cookies.txt
P115_CHECK_FOR_RELOGIN=true
P115_ALLOW_QRCODE_LOGIN=false
P115_CONSOLE_QRCODE=false
通用 stdio 模板
如果某个客户端支持以 command + args + env 的方式添加 MCP 服务,可直接套用:
{
"mcpServers": {
"115-MCP-Server": {
"command": "C:\\Users\\flami\\Downloads\\115-MCP\\.venv\\Scripts\\python.exe",
"args": ["-m", "mcp_115_server"],
"env": {
"P115_COOKIES_PATH": "C:\\Users\\your-name\\115-cookies.txt",
"P115_CHECK_FOR_RELOGIN": "true",
"P115_ALLOW_QRCODE_LOGIN": "false",
"P115_CONSOLE_QRCODE": "false"
}
}
}
}
大多数支持 MCP 的客户端,本质上都只需要以下两种接入方式之一:
stdiohttp
无论你使用的是 OpenCode、Claude Code、Claude Desktop、Cursor、Gemini、Kiro、Antigravity、Cherry Studio,还是其它支持 MCP 的客户端,都建议优先按下面的通用模板配置。
HTTP 模式接入
如果客户端支持通过 URL 连接 MCP,可使用 HTTP 模式。
先启动服务:
powershell -ExecutionPolicy Bypass -File .\scripts\run-http.ps1
默认地址:
http://127.0.0.1:8000/mcp
然后在客户端中填入这个地址即可。
接入排查建议
如果某个客户端接入失败,优先检查:
- 客户端版本是否真的支持 MCP
- 是否选择了
stdio或 HTTP MCP 模式 - Python 路径是否正确
- 是否使用了正确的
python.exe与-m mcp_115_server入口 - cookies 是否已正确配置
- HTTP 模式下端口和路径是否为
127.0.0.1:8000/mcp
使用方式
常见使用流程 1:已有 cookies,直接使用
- 配置环境变量
- 启动服务
- 在客户端中调用:
auth_statuslist_directorysearch_entriesoffline_add_urls
常见使用流程 2:没有 cookies,先扫码登录
- 启动服务
- 调用
start_qrcode_login - 打开返回的
qrcode_url并扫码 - 调用
get_qrcode_login_status轮询状态 - 状态变成
signed_in后,调用finish_qrcode_login - 保存返回的 cookies,后续直接复用
常见使用流程 3:离线下载资源到 115
- 先用
create_directory创建目标目录 - 用
offline_add_urls添加下载链接 - 用
offline_list_tasks或offline_list_tasks_advanced查询进度 - 必要时用:
offline_restart_taskoffline_remove_taskoffline_remove_tasksoffline_clear_tasks
常见使用流程 4:整理和管理文件
可组合调用:
list_directorysearch_entriesmove_entry/batch_move_entriesrename_entryset_entry_labelsget_download_url
项目结构
src/mcp_115_server/
config.py # 环境变量与服务配置
service.py # 115 业务封装层
server.py # FastMCP 工具注册与服务入口
tests/
test_service.py
scripts/
run-stdio.ps1
run-http.ps1
run-stdio.cmd
run-http.cmd
MCP 工具
auth_statuslist_directoryget_metadatasearch_entriescreate_directoryresolve_directoryget_storage_infostart_qrcode_loginget_qrcode_login_statusfinish_qrcode_loginget_account_infoget_index_infopath_existscount_directoryget_ancestorsglob_entrieswalk_directoryget_statoffline_add_urlsoffline_get_torrent_infooffline_add_torrentoffline_list_tasksoffline_find_tasksoffline_remove_taskoffline_clear_tasksoffline_get_quota_infooffline_get_download_pathsoffline_set_download_pathoffline_restart_taskoffline_get_task_countoffline_list_tasks_advancedoffline_remove_tasksoffline_get_sign_infooffline_get_quota_package_arrayoffline_get_quota_package_infolist_recycle_binget_recycle_bin_entryrestore_recycle_bin_entriesclear_recycle_binlist_labelsset_entry_labelslist_sharesget_share_infoget_share_receive_codereceive_share_entriesget_share_download_urllist_share_access_usersget_share_download_quotaupload_local_filedownload_filemove_entrybatch_move_entriescopy_entrybatch_copy_entriesrename_entryremove_entrybatch_remove_entriesget_download_url
关键返回约定
-
get_download_url始终返回对象,而不是裸字符串,包含:url: 当前下载地址target: 目标文件的元数据
-
auth_status(validate_remote=true)在远端校验失败时会返回:remote_logged_in: falseremote_error: 规范化后的错误消息
-
批量操作工具统一支持两种来源之一:
source_ids: list[int]source_paths: list[str]
两者只能传一个。
-
get_share_download_url始终返回对象,包含:urlfile_idmode
新增能力说明
1. 批量移动
一次移动多个文件或目录到目标目录:
batch_move_entries(source_ids=[...], destination_dir_path="/目标目录")batch_move_entries(source_paths=["/a.txt", "/b"], destination_dir_id=123456)
2. 批量复制
一次复制多个文件或目录到目标目录:
batch_copy_entries(source_ids=[...], destination_dir_path="/目标目录")
3. 批量删除
一次删除多个文件或目录:
batch_remove_entries(source_ids=[...])batch_remove_entries(source_paths=["/旧文件.txt", "/旧目录"])
4. 查询目录 ID
如果你手里是一个目录路径,可以先调用:
resolve_directory(remote_path="/文档/项目")
5. 查询空间信息
获取当前账号空间配额信息:
get_storage_info()
5.1 扫码登录获取 cookies
现在可以直接通过 MCP 工具完成二维码登录,不必预先手动准备 cookies。
步骤 1:启动扫码会话
start_qrcode_login(app="alipaymini")
返回:
session_iduidqrcode_urlapp
步骤 2:轮询扫码状态
get_qrcode_login_status(session_id="...")
可能的 status_name:
waitingscannedsigned_inexpiredcanceled
步骤 3:完成登录并保存 cookies
finish_qrcode_login(session_id="...", output_path="C:\\Users\\your-name\\115-cookies.txt")
返回:
cookiessaved_tosession_id
完成后,这个 MCP 服务实例会立即切换到新的 cookies。
6. 路径/目录辅助查询
path_exists(remote_path="/文档")count_directory(remote_path="/文档")get_ancestors(remote_path="/文档/项目/demo.txt")glob_entries("*.txt", directory_path="/文档")walk_directory(remote_path="/文档", max_depth=2)get_stat(remote_path="/文档/demo.txt")
7. 离线下载(重点能力)
已实现的离线下载工具:
offline_add_urls(urls=[...], remote_dir_id=123)offline_get_torrent_info(torrent_sha1="...", pick_code="...")offline_add_torrent(torrent_sha1="...", pick_code="...", wanted_indexes=[0,1])offline_list_tasks(page=1)offline_find_tasks(query="字幕组", status="completed")offline_remove_task(info_hash="...", delete_source_file=false)offline_clear_tasks(scope="completed")offline_get_quota_info()offline_get_download_paths()offline_set_download_path(remote_dir_path="/文档/离线")offline_restart_task(info_hash="...")offline_get_task_count(flag=0)offline_list_tasks_advanced(page=1, page_size=30, status="completed")offline_remove_tasks(info_hashes=["...", "..."], delete_source_file=false)offline_get_sign_info()offline_get_quota_package_array()offline_get_quota_package_info()
offline_clear_tasks 支持的 scope:
completedallfailedin_progresscompleted_and_delete_sourceall_and_delete_source
说明:
offline_add_urls适合 HTTP / HTTPS / FTP / magnet / ed2koffline_add_urls不支持直接提交.torrent文件- 如果你要添加 BT 种子任务,应使用:
offline_get_torrent_infooffline_add_torrent
offline_get_torrent_info可先查看 BT 内容,再配合wanted_indexes精选文件offline_list_tasks已经对 Open API 的响应结构做了整形,直接返回count / page_count / tasksoffline_find_tasks会在 MCP 层基于分页结果执行本地搜索/过滤,支持:queryinfo_hashstatuslimitoffset
offline_set_download_path可以用remote_dir_id或remote_dir_path指定默认离线目录offline_restart_task适合失败后的任务重试offline_get_task_count直接返回后端的离线任务计数信息offline_list_tasks_advanced支持传统离线任务状态筛选,当前支持:failedcompletedin_progress
offline_remove_tasks用于按info_hash批量删除离线任务offline_get_sign_info返回低层离线接口会用到的sign/time等信息offline_get_quota_package_array/offline_get_quota_package_info返回更详细的离线套餐/配额信息
8. 回收站
list_recycle_bin(limit=32, offset=0)get_recycle_bin_entry(rid=123)restore_recycle_bin_entries(entry_ids=[1,2,3])clear_recycle_bin(entry_ids=[1,2], password="123456")
说明:
- 不传
entry_ids时表示清空整个回收站 - 如果你的 115 账号开启了安全密钥校验,需传
password
9. 标签
list_labels(keyword="项目")set_entry_labels(remote_id=123456, label_ids=[1,2])
注意:set_entry_labels 是替换当前标签集合,不是追加。
- 传
label_ids=[]表示清空这个条目的全部标签
10. 分享
list_shares(limit=32, offset=0)get_share_info(share_code="xxxx")get_share_receive_code(share_code="xxxx")receive_share_entries(share_code="xxxx", receive_code="abcd", file_ids=[1,2], remote_dir_path="/接收目录")get_share_download_url(file_id=123, share_code="xxxx", receive_code="abcd")list_share_access_users(share_code="xxxx")get_share_download_quota()
说明:
get_share_download_url支持两种方式:- 显式传
share_code + receive_code + file_id - 或直接传
share_url + file_id
- 显式传
get_share_download_url始终返回对象:url: 下载地址file_id: 请求的分享文件 idmode:share_code或share_url
receive_share_entries会把分享中的指定文件/目录接收到你自己的网盘目录中
11. 账号与首页统计
get_account_info()get_index_info(include_space_numbers=true)
目标定位规则
大多数工具都支持以下两种方式之一:
remote_id: 115 文件/目录 IDremote_path: 115 路径,例如/文档/项目
两者只能传一个;目录类工具若都不传,则默认根目录。
远程 ID 传参规则(重要)
所有远程 ID 都建议并推荐按字符串传入,不要按 JSON number / 数值传入。
正确示例:
{
"remote_id": "3398357158620823140"
}
不推荐示例:
{
"remote_id": 3398357158620823140
}
原因:
- 115 的很多远程 ID 很长
- 在某些客户端、语言运行时、JSON 处理中,超长整数可能发生精度丢失
- 一旦被改写,例如尾数被截断或归整,就会导致操作到错误的文件或目录
因此:
remote_idparent_iddirectory_idremote_dir_idsource_iddestination_dir_idfile_idridsource_idsentry_idsfile_idslabel_ids
都应优先按字符串或字符串数组传入。
测试
./.venv/Scripts/python -m unittest discover -s tests -v
本地打包为 Windows exe
如果你需要在本地构建 Windows 可执行文件:
./.venv/Scripts/python -m pip install pyinstaller
powershell -ExecutionPolicy Bypass -File .\scripts\build-exe.ps1
构建完成后输出位于:
dist\115-MCP-Server.exe
说明:
- 这是基于当前虚拟环境依赖打包出的 Windows 可执行文件
- 配置仍然通过环境变量或 MCP 客户端
environment传入
部署建议
- 本地桌面客户端优先使用
stdio - 需要多客户端共享时使用
http - cookies 推荐放在本机文件中,通过
P115_COOKIES_PATH引用 - 不建议把真实 cookies 直接写进公开配置文件
常见问题
1. 提示未配置认证
说明没有设置 P115_COOKIES 或 P115_COOKIES_PATH。
2. 提示 cookies 文件不存在
确认 P115_COOKIES_PATH 指向真实文件,路径需要是运行客户端那台机器上的本地路径。
3. 客户端连不上 MCP
检查:
- Python 路径是否正确
- 虚拟环境是否已安装
pip install -e . - 客户端配置里的
args是否为-m mcp_115_server
4. HTTP 模式无法访问
检查端口是否被占用,以及客户端填写的地址是否为:
http://127.0.0.1:8000/mcp
