MCP 接入

通过 MCP,将 WPS笔记接入支持该协议的 AI 客户端,按授权搜索、读取或编辑笔记。实际可用操作以当前连接的工具列表和凭证权限为准。

选择连接方式

选择一种连接方式,完成对应章节后直接进入「验证连接」,无需依次配置全部方式。

连接方式 使用条件 凭证来源
云端 MCP 不需要本机 WPS笔记客户端持续运行。 在云端 MCP 凭证管理中创建 API Key,并复制完整配置。
本地 MCP 提供服务的电脑和 WPS笔记客户端需要保持运行。 在本地 MCP 设置中创建 Token,并使用本地地址。

已安装云端 wpsnote-cli 的用户,也可以选择「使用云端命令行连接」。该方式使用独立的浏览器授权流程。

云端 MCP 连接

1. 打开云端配置

打开 WPS笔记的「AI 实验室」,在「云端 MCP」区域点击「配置」。云端连接无需保持本机 WPS笔记客户端运行。

在 AI 实验室中打开云端 MCP 配置

2. 创建 API Key

点击「创建 Key」,输入名称并选择权限。仅查询笔记时选择「只读」;需要编辑时选择「读写」。阅读授权提示并确认后,点击「创建」。

创建 API Key 并选择权限

3. 连接客户端

点击凭证右侧的客户端导入按钮,或点击「复制 JSON 配置」,在 AI 客户端的 MCP 设置中导入并启用服务。两种方式任选其一。

Cherry Studio 的配置步骤见 Cherry Studio 接入教程。

云端凭证列表中的权限、过期时间和客户端导入入口(敏感信息已遮挡)

右侧图标依次为「复制 JSON 配置」「导入 Cherry Studio」「导入 Cursor」和「删除」。截图日期仅作示例,有效期以你的凭证为准。

云端地址:https://ainote.kdocs.cn/mcp-svc/mcp。请使用凭证管理页提供的完整配置,不要混用本地地址或 Token。配置完成后,按下文「验证连接」检查搜索和读取。

本地 MCP 连接

以下保留官网原有截图,展示本地服务的开启与配置流程。具体入口名称以安装版本为准。截图中的 127.0.0.1 地址和本地 Token 仅用于本地连接;提供服务的电脑和 WPS笔记客户端需要保持运行。

  1. 开启 MCP

    • 点击左下角设置按钮
    • 进入 AI 实验室
    • 开启 MCP 开关
    • 完成 AI 实验室准入评估

    开启 MCP

  2. 创建 Token

    • 点击「创建新 Token」
    • 输入 wpsnote
    • 点击创建生成密钥

    创建 Token

  3. 连接客户端

    • 点击设置页提供的 Cherry Studio / Cursor / OpenClaw 导入入口,在对应客户端确认配置。
    • 如果没有自动打开客户端,请手动启动客户端,再按设置页提供的本地地址和 Token 配置。

    连接客户端

完成配置后,在客户端启用服务并进入「验证连接」。Cherry Studio 的本地配置截图见 Cherry Studio 接入教程。

使用云端命令行连接

本节适用于已经安装云端 wpsnote-cli 的用户,不是本地 MCP 的后续步骤。尚未安装时,可以先使用上面的云端或本地客户端配置;本页不包含 CLI 安装步骤。

在终端依次执行以下命令,通过浏览器授权建立只读连接并查看工具:

wpsnote-cli auth login --scope read
wpsnote-cli auth status
wpsnote-cli tools list

在授权页确认「只读」后,CLI 可以查看和搜索笔记,不能修改或删除。状态检查和列出工具只能证明授权与工具发现成功,笔记读取仍需按下一节验证。

CLI 浏览器授权与其他 MCP 客户端的配置方式不同,不应据此假定所有客户端都支持同一授权流程。

验证连接

  1. 确认客户端已启用 WPS笔记 MCP,并能够列出当前授权范围内的工具。CLI 用户使用 wpsnote-cli tools list 检查工具发现。
  2. 在 AI 客户端中搜索一篇你允许读取的已知笔记,并核对搜索结果。CLI 用户按 wpsnote-cli --help 及具体工具帮助中的调用格式执行相应搜索工具。
  3. 读取该笔记的少量正文,并与 WPS笔记中的原文核对。搜索和读取都成功后,即可完成只读连接验证。

只读连接无需测试写入。只有确实需要写入、已授予相应权限并明确允许操作时,才创建一篇测试笔记并核对结果。不要在正式笔记上尝试修改。

常见问题与故障排查

需要一直运行 WPS笔记客户端吗?

云端 MCP 不需要。本地 MCP 需要提供服务的电脑和 WPS笔记客户端保持运行;本地服务停止后,该连接将不可用。

客户端没有打开或没有显示工具怎么办?

  1. 先确认当前使用云端还是本地连接,再核对设置页提供的地址、连接方式和凭证。
  2. 如果导入入口没有打开客户端,请手动启动客户端并导入配置;部分客户端可能需要重新加载服务或新建会话,具体以客户端当前版本说明为准。
  3. 如果使用本地连接,请确认本地服务开关已开启,且对应电脑和 WPS笔记客户端仍在运行。
  4. 如果仍未显示工具,请检查客户端是否支持该连接方式,并重新加载 MCP 配置。

提示未授权或无法读取笔记怎么办?

检查凭证是否填写完整、是否已删除或失效。云端 API Key、本地 Token 和 CLI 浏览器授权属于不同配置,不要混用。请使用你有权访问且允许测试的笔记验证。

可以读取但不能写入怎么办?

只读凭证不能写入,这是预期行为。确实需要写入时,先确认凭证权限及工具列表包含相应操作,再明确授权测试;只读验收不需要扩大权限。

云端凭证到期后怎么办?

云端 API Key 有有效期,可以在 云端 MCP 凭证管理查看「过期时间」。具体到期时间以该页面为准,不要仅根据创建日期推算。

如果原本可用的连接提示未授权,请先检查凭证是否到期、被删除或失效。凭证到期后,为客户端创建新的 API Key,复制完整 JSON 配置或重新使用导入入口,更新原服务配置并重新加载。随后搜索并读取一篇已知笔记,确认连接恢复;不需要为此扩大权限。

凭证到期不代表云端服务地址失效。请更新对应凭证,不要改用本地 Token 或其他来源的配置。

使用 CLI 浏览器授权时,如果服务端提供刷新凭证,CLI 会尝试续期;无法续期时,重新执行 wpsnote-cli auth login --scope read 并完成授权。该续期行为不能直接套用于其他客户端的 API Key 配置。

凭证安全

API Key、Token 和浏览器授权产生的访问凭据均可用于访问笔记,不应写入公开文档、截图或代码仓库。云端 API Key 和本地 Token 应分别用于对应连接,不要混用。

若怀疑泄露,请在对应凭证管理页面删除该凭证,并为客户端重新配置。仅查询笔记时使用只读权限;AI 客户端如何处理笔记内容,还取决于客户端和模型配置,不能仅根据 MCP 服务位置判断。

对比其他笔记应用

查看 笔记应用 MCP 支持对比,了解各应用的连接方式、读写能力和使用条件。

英文版:Compare MCP support in note apps。