Mi Note MCP

🚀 mi_note_mcp

mi_note_mcp is a server implementation of Xiaomi Cloud Notes based on the Model Context Protocol (MCP). It enables MCP - supported assistants (such as Claude and ChatGPT Desktop) to directly read, search, create, and manage your cloud notes. The project caches interface results locally and provides the ability to convert between Markdown and XML, allowing large - language models to handle note content seamlessly.

🚀 Quick Start

1. Install Dependencies

bun install

2. Configure Credentials

Before starting the service, you need to prepare a configuration file. The default path is ~/.mi - note - mcp.json, or you can specify another location through the environment variable MI_NOTE_MCP_CONFIG.

Configuration example:

{
  "serviceToken": "YOUR_SERVICE_TOKEN",
  "userId": "YOUR_USER_ID",
  "passToken": "Optional, enhances login stability",
  "slh": "Optional",
  "ph": "Optional",
  "deviceId": "Optional, used to be consistent with the web page",
  "cUserId": "Optional",
  "uLocale": "zh_CN",
  "syncInterval": 30000,
  "baseUrl": "https://i.mi.com"
}

It is recommended to log in to Xiaomi Cloud Notes in the browser, then copy the Cookie fields (such as serviceToken, userId, passToken, etc.) in the request header through the developer tools, and ensure that these fields are valid for a long time. syncInterval is in milliseconds and is used to control the frequency of background incremental synchronization.

3. Start the MCP Server

bun run index.ts

After successful startup, the terminal will output mi - note - mcp server started. Then you can register mi_note_mcp as a local service in an MCP - supported client and fill in the command and working directory according to the client's instructions.

✨ Features

• Reading, Searching, and Caching: Supports listing, searching, and viewing note details, and automatically maintains local caches to reduce repeated network requests.
• Complete Note Editing Chain: Provides common operations such as creating, updating, deleting, and moving notes, and automatically synchronizes resource status.
• Folder Management: Supports listing, creating, renaming, and deleting folders, and viewing notes by folder.
• Rich - Text Conversion: Converts between Markdown and Xiaomi Notes' internal XML, retaining formats such as task lists, images, and bold text.
• Image Upload: Uploads local images to the Xiaomi cloud and returns reusable links in the form of minote://image/{fileId}.
• MCP Resource Exposure: Exposes URIs of note and folder - related resources for easy context completion and navigation.

📦 Installation

Environment Requirements

• Bun ≥ 1.1 (Developed and tested with 1.2.23)
• A Xiaomi account that can access https://i.mi.com/note
• Node.js TypeScript ecosystem (only required for development/type checking)

📚 Documentation

Tools

Resources

🔧 Technical Details

Caching and Synchronization Mechanism

• On the first startup, it retrieves full - volume data via /note/full/page and caches it in memory.
• Subsequently, it calls the incremental synchronization interface according to syncInterval (default 30 seconds) to update the status of notes and folders.
• After a write operation, the tool actively refreshes the cache and triggers resource updates, ensuring that the MCP client's UI and context immediately sense changes.
• You can force a refresh in the code using the refresh() method of NotesCache (most tools call this method automatically).

Development and Testing

• Type Checking (recommended to run before submission):

bun run tsc --noEmit --skipLibCheck

• Unit Testing:

bun test

During development, it is recommended to follow the existing code style and directory structure in the repository. Refer to the test cases under tests/ to understand the behavior of key modules when necessary.

💡 Usage Tip

• If it prompts that the configuration file does not exist: Confirm whether ~/.mi - note - mcp.json is created successfully, or set the correct MI_NOTE_MCP_CONFIG.
• If it returns 401/403: Usually, cookies such as serviceToken and userId have expired. Copy them again from the web - page and update the configuration, then try again.
• If image upload fails: Check if the file exists, if the MIME type is correct, or if the network can access i.mi.com.

If you need to extend additional tools or resources, please reuse the existing client and caching logic first and follow the project's KISS/YAGNI principle.