mi_note_mcp

mi_note_mcp 是一个基于 Model Context Protocol (MCP) 的小米云笔记服务器实现，可让支持 MCP 的助手（如 Claude、ChatGPT 桌面端等）直接读取、搜索、创建和管理你的云端笔记。项目在本地对接口结果做缓存，并提供 Markdown/XML 互转能力，让大语言模型能够无缝处理笔记内容。

功能特性

读取、搜索与缓存：支持列出、搜索、查看笔记详情并自动维护本地缓存，减轻重复网络请求。
完整的笔记编辑链路：提供创建、更新、删除、移动笔记等常见操作，并自动同步资源状态。
文件夹管理：支持列出、创建、重命名、删除文件夹及按文件夹查看笔记。
富文本转换：在 Markdown 与小米笔记内部 XML 之间相互转换，保留任务列表、图片、粗体等格式。
图片上传：可将本地图片上传至小米云端并返回 minote://image/{fileId} 形式的可复用链接。
MCP 资源暴露：暴露笔记、文件夹相关资源 URI，方便上下文补全与导航。

环境要求

Bun ≥ 1.1（开发测试使用 1.2.23）
一个可以访问 https://i.mi.com/note 的小米账号
Node.js TypeScript 生态（仅在开发/类型检查时需要）

快速开始

1. 安装依赖

bun install

2. 配置凭据

服务启动前需要准备配置文件，默认路径为 ~/.mi-note-mcp.json，也可以通过环境变量 MI_NOTE_MCP_CONFIG 指定其他位置。

配置示例：

{ "serviceToken": "YOUR_SERVICE_TOKEN", "userId": "YOUR_USER_ID", "passToken": "可选，增强登录稳定性", "slh": "可选", "ph": "可选", "deviceId": "可选，用于与网页保持一致", "cUserId": "可选", "uLocale": "zh_CN", "syncInterval": 30000, "baseUrl": "https://i.mi.com" }

获取方式建议在浏览器登录小米云笔记后，通过开发者工具复制请求头中的 Cookie 字段（如 serviceToken、userId、passToken 等），并保证这些字段长期有效。syncInterval 以毫秒为单位，用于控制后台增量同步频率。

3. 启动 MCP 服务器

bun run index.ts

启动成功后，终端会输出 mi-note-mcp server started。随后即可在支持 MCP 的客户端中把 mi_note_mcp 注册为本地服务，按客户端指引填写命令与工作目录。

MCP 工具与资源

工具（Tools）

工具 ID	功能说明	关键参数
`list_notes`	列出缓存中的全部笔记	无
`get_note`	按 ID 获取笔记 Markdown 内容	`id`
`create_note`	创建新笔记并返回资源链接	`content` 、 `title?` 、 `folderId?`
`update_note`	更新笔记内容与元数据	`id` 、 `content` 、 `title?` 、 `folderId?`
`delete_note`	删除或永久删除笔记	`id` 、 `purge?`
`move_note`	将笔记移动到指定文件夹	`noteId` 、 `folderId`
`search_notes`	关键词搜索标题与摘要	`keyword` 、 `limit?`
`upload_image`	上传图片并返回 `minote://image/{fileId}`	`path` 、 `mimeType?`
`list_folders`	列出全部文件夹	无
`create_folder`	创建文件夹	`subject` 、 `parentId?`
`update_folder`	重命名文件夹	`id` 、 `subject`
`delete_folder`	删除或永久删除文件夹	`id` 、 `purge?`

资源（Resources）

资源 URI	内容	说明
`minote://notes`	所有笔记的概览列表	支持资源列表变更通知
`minote://notes/{id}`	指定笔记的 Markdown 内容	自动缓存并保持最新
`minote://folders`	文件夹概览	列表随同步自动刷新
`minote://folders/{id}/notes`	指定文件夹下的笔记列表	结合 `move_note` 可快速浏览整理

缓存与同步机制

首次启动会通过 /note/full/page 获取全量数据并缓存到内存。
之后按照 syncInterval（默认 30 秒）调用增量同步接口更新笔记与文件夹状态。
工具在执行写操作后会主动刷新缓存并触发资源更新，保证 MCP 客户端侧 UI 与上下文立即感知变化。
可以通过 NotesCache 的 refresh() 方法在代码中强制刷新（大部分工具已自动调用）。

开发与测试

类型检查（推荐在提交前运行）：
bun run tsc --noEmit --skipLibCheck
单元测试：
bun test

开发时建议遵循仓库内现有的代码风格与目录结构，必要时参考 tests/ 下用例了解关键模块行为。

常见问题

提示配置文件不存在：确认 ~/.mi-note-mcp.json 是否创建成功，或设置正确的 MI_NOTE_MCP_CONFIG。
返回 401/403：通常是 serviceToken、userId 等 cookie 过期，重新从网页端复制并更新配置后重试。
图片上传失败：检查文件是否存在、MIME 类型是否正确，或网络是否可访问 i.mi.com。

如需扩展额外工具或资源，请优先复用现有客户端与缓存逻辑，遵守项目的 KISS/YAGNI 原则。

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables interaction with Xiaomi Cloud Notes through MCP, allowing AI assistants to read, search, create, manage notes and folders with automatic Markdown/XML conversion and image upload support.

Mi Note MCP Server