金大哥 - mi_note_mcp MCP 详情

article

README

🚀 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 原则。

mi_note_mcp