Milanote by Cotlet

Milanote API 和 MCP 服务，可自托管

一个 Milanote API 和 Milanote MCP 服务，使用 Python 在你自己的电脑上运行，并通过你自己的 Google Chrome 会话工作。我们在 Cotlet 的生产环境中运行的 31 个 Milanote 工具中，这里包含 30 个：看板、笔记、链接、带截止日期的待办清单、列、标签、回收站、评论、共享和导出。

Milanote 没有公开 API，也没有官方 MCP 服务。本仓库为你提供这两者：

• 适用于 Claude Code、Claude Desktop、Cursor、Codex 和任何 MCP 客户端的 MCP 服务，支持 stdio 或 HTTP。设置
• 位于 http://127.0.0.1:8787/api/v1/milanote 的 REST API，OpenAPI 文档位于 /docs。设置
• Python：call("get_board", board_id="1XiqwC1Mir4d4N")，另有 examples/ 中的 9 个现成脚本。

本项目面向希望自行运行它的技术人员，仅限非商业用途（许可证）。如果你希望它在服务上全天候运行、在 Milanote 更改应用后仍能正常工作，或供团队或企业使用，请使用 cotlet.dev 上托管的版本。

git clone https://github.com/cotletdev/milanote-api-mcp-server.git && cd milanote-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
milanote-mcp connect                               # reads your Milanote session from Chrome
milanote-mcp call list_boards
claude mcp add milanote -- "$PWD/.venv/bin/milanote-mcp" mcp

目录

• 工作原理
• 要求
• 安装
• 连接你的 Chrome
• MCP 服务
• REST API
• Python 和示例脚本
• 全部 30 个工具
• 配置
• 安全性和你的 Milanote 账户
• 错误
• 自托管或托管版本
• 常见问题
• 许可证

工作原理

AI agent (MCP) / script (REST, Python) ──▶ milanote-mcp on your computer ──your Milanote cookies──▶ milanote.com
                                                     ▲
                         milanote-mcp connect ───────┘ reads them once from your Chrome (DevTools Protocol)

1. 像往常一样，在自己的 Chrome 中登录 Milanote。
2. milanote-mcp connect 通过 Chrome DevTools Protocol 连接到该 Chrome，读取 milanote.com Cookie 和浏览器时区，并将它们保存到 ~/.config/milanote-api-mcp/session.json，该文件仅对你的用户可读。它不会查看或存储你的密码。
3. 读取操作会请求 Milanote Web 应用在 app.milanote.com/api 上的 JSON 端点。更改操作通过 Web 应用使用的同一 socket.io 通道发送，并使用纯 HTTP 轮询。所有请求都会通过 curl_cffi 携带你的 Cookie 发出；它会复制 Chrome 的 TLS 指纹。不会运行无头浏览器。

Milanote 会话 Cookie 的有效期约为一个月。当 Milanote 将你登出时，如果 Chrome 已开启远程调试，服务会再次从 Chrome 读取 Cookie。

要求

• Python 3.11 或更新版本。
• Google Chrome 144 或更新版本，并已登录 Milanote。任何 Chrome 或 Chromium 都可配合调试端口使用。
• macOS、Linux 或 Windows。
• 任何 Milanote 套餐。免费账户最多支持 100 张卡片；当 Milanote 拒绝操作时，工具会说明这一点。要更改他人分享给你的看板，你需要拥有该看板的编辑权限。

安装

git clone https://github.com/cotletdev/milanote-api-mcp-server.git
cd milanote-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
milanote-mcp --version

使用 uv：运行 uv venv && uv pip install -e .，然后运行 uv run milanote-mcp ...。

要使用 AI Agent（Claude Code、Codex、Cursor）设置本项目？在此文件夹中打开它，并要求它设置仓库：AGENTS.md 会告知它每个步骤；它只会让你执行 Chrome 中的步骤。

更新方式：git pull && pip install -e .。我们会将托管版 Milanote 工具的每项更改同步到此仓库。

连接你的 Chrome

选项 A：日常使用的 Chrome（推荐）

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，并开启远程调试。随后，Chrome 会接受此计算机上程序发起的 DevTools 连接，并在每次连接前征求你的同意。

2. 确保你已登录 app.milanote.com。

3. 运行：

   milanote-mcp connect
   

4. Chrome 会询问是否允许连接。点击允许。

Saved 8 Milanote cookies to /Users/you/.config/milanote-api-mcp/session.json
Signed in to Milanote as Ana Lopez

之后你可以再次关闭远程调试。如果你希望 Milanote 将你登出后，服务能自动获取新会话，请保持开启。

connect 会在默认配置文件夹中查找 Chrome 的 DevToolsActivePort 文件。对于 Chrome Beta、Canary 或自定义配置文件夹，请传入 --profile-dir "<folder>"。

选项 B：使用带调试端口的 Chrome

Chrome 不会在默认配置文件上开放调试端口，因此请启动一个独立配置文件，在其中登录一次 Milanote，然后连接到它：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-milanote"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-milanote"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-milanote"

milanote-mcp connect --cdp http://127.0.0.1:9222

--cdp 也接受 ws:// DevTools URL，例如通过 SSH 隧道连接到另一台计算机上的 Chrome。

选项 C：手动粘贴 Cookie

对于没有 Chrome 的服务：在 Chrome 中打开 app.milanote.com 的 DevTools，进入**Application > Cookies > https://app.milanote.com**，复制 __Secure-milanote.session_token 的值，然后：

milanote-mcp connect --token       # paste it, input is hidden
# or, without a session file:
export MILANOTE_AUTH_TOKEN=...

粘贴的令牌不会自动刷新。Milanote 将你登出后，请粘贴新的令牌。此时的时间会采用这台计算机的时区。

随时检查会话：

milanote-mcp status

MCP 服务

MCP 服务会列出每个工具及其输入架构、面向 Agent 编写的说明和提示：读取工具会标记为只读；评论、邀请、发布或移至回收站的工具也会标记出来，以便客户端在运行前征求你的同意。

Claude Code

claude mcp add milanote -- /path/to/milanote-api-mcp-server/.venv/bin/milanote-mcp mcp
# read only:
claude mcp add milanote -- /path/to/milanote-api-mcp-server/.venv/bin/milanote-mcp mcp --read-only

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "milanote": {
      "command": "/path/to/milanote-api-mcp-server/.venv/bin/milanote-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json，与 Claude Desktop 使用相同的配置块。可直接使用的副本位于 mcp.json。

Codex

~/.codex/config.toml：

[mcp_servers.milanote]
command = "/path/to/milanote-api-mcp-server/.venv/bin/milanote-mcp"
args = ["mcp"]

通过 HTTP

milanote-mcp serve 也会通过 http://127.0.0.1:8787/mcp 提供可流式传输的 HTTP MCP，供接受 URL 的客户端使用：

milanote-mcp serve
claude mcp add --transport http milanote http://127.0.0.1:8787/mcp

然后可以向你的 Agent 提出以下请求：

将这 12 个参考链接放到 Brand refresh 的 Moodboard 子看板上，并跳过已存在的链接。

将我的 Novel outline 看板及各章节子看板导出为 Markdown，保存到 ./outline。

这是我的通话记录。将待办事项和我们商定的日期添加到 Q1 campaign 的待办清单中。

我把那条关于配色方案的笔记保存在哪里了？

REST API

milanote-mcp serve                 # http://127.0.0.1:8787, MCP at /mcp, docs at /docs

每个工具在 /api/v1/milanote 下都有自己的路由，与 cotlet.dev 上托管的 API 使用相同路径，因此针对其中一个编写的代码也适用于另一个。路径部分和查询字符串会作为参数，JSON 请求体则提供其余参数。

curl 'http://127.0.0.1:8787/api/v1/milanote/boards'
curl 'http://127.0.0.1:8787/api/v1/milanote/boards/1XiqwC1Mir4d4N'
curl -X POST http://127.0.0.1:8787/api/v1/milanote/boards/1XiqwC1Mir4d4N/notes \
  -H 'Content-Type: application/json' \
  -d '{"text": "Kickoff moved to Tuesday."}'

按名称调用任意工具，并将请求体作为其参数：

curl -X POST http://127.0.0.1:8787/api/v1/milanote/tools/export_board -d '{"board_id": "1XiqwC1Mir4d4N", "format": "markdown"}'

• GET /api/v1/milanote/tools：列出每个工具及其路由、输入架构和示例回答。
• GET /docs：交互式 OpenAPI 文档；GET /openapi.json：架构，可用于 n8n、Postman 或生成的客户端。
• 回答均为 JSON。提前停止的列表会返回 has_more: true；提高 limit 即可获取剩余内容。

服务仅监听 127.0.0.1。如需从你的另一台设备访问，请设置令牌，此后每个请求都需要携带 Authorization: Bearer <token>：

MILANOTE_MCP_TOKEN=$(openssl rand -hex 24) milanote-mcp serve --host 0.0.0.0

Python 和示例脚本

直接使用 Python，无需服务端：

from milanote_api_mcp import call

boards = call("list_boards")["boards"]
board = call("get_board", board_id=boards[0]["id"])
call(
    "add_todo_list",
    board_id=board["board_id"],
    title="This week",
    tasks=[{"text": "Send the brief", "due_date": "2026-10-28"}, {"text": "Book the photographer"}],
)

也可以在命令行中调用单个工具：milanote-mcp call get_board board_id=1XiqwC1Mir4d4N，或使用 JSON 对象。

可直接使用的脚本位于 examples/ 中。每个脚本都支持 --help；用于列出内容的脚本会输出 JSON，或保存为 --out file.csv / --out file.json：

脚本	功能
list_boards.py	以树状结构列出你的画板，从主页或任意画板开始，向下显示指定的 --depth 层。
search_boards.py	搜索你的所有画板，并列出每个匹配卡片及其所属画板和路径。
export_boards.py	将一个画板及其子画板导出为 Markdown、文本、Word、PDF 或 PNG；每个画板生成一个文件，文件夹结构与嵌套层级一致。
board_card_counts.py	按类型统计每个画板中的卡片数，按数量从多到少排列，并显示你对免费方案限额的使用情况。
open_tasks.py	列出一个画板及其子画板中所有待办清单里未勾选的任务，并按截止时间从近到远排列。支持 --due-before。
save_links.py	将 URL 列表保存为链接卡片，跳过画板中已有的链接。可先使用 --dry-run。
add_todo_list.py	根据文本文件创建待办清单，每行一项任务，可选添加 YYYY-MM-DD HH:MM 格式的截止时间。
add_note.py	根据 --text、文件或标准输入创建笔记卡片。
publish_board.py	开启画板的只读链接并将其打印出来，或使用 --off 关闭。

python examples/export_boards.py --board 1XiqwC1Mir4d4N --dir ./outline
python examples/save_links.py --board 1XiqwC1Mir4d4N --file links.txt --dry-run

可以按计划定期运行。只要电脑处于开机状态，就可以使用本机上的 cron：0 18 * * 5 cd ~/milanote-api-mcp-server && .venv/bin/python examples/export_boards.py --board 1XiqwC1Mir4d4N --dir ~/backups/milanote。

全部 30 个工具

board_id 是 list_boards 返回的 ID，也可以使用画板 URL（https://app.milanote.com/1XiqwC1Mir4d4N/...）。工具添加的卡片会放在画板的「未分类」面板中，也就是 Milanote 放置上传内容的位置，因此不会覆盖画布上的卡片。运行 milanote-mcp tools 可打印此列表，运行 milanote-mcp tools --json 可显示输入架构。

画板

工具	权限	REST 路由	功能
list_boards	读取	GET /boards	列出一个画板内的画板，默认列出主页上的画板，并显示标题、ID 和链接。
list_recent_boards	读取	GET /boards/recent	按最近打开时间从新到旧列出你打开过的画板，无论它们位于画板树中的何处。
search_boards	读取	GET /boards/search	在你的所有画板中按文本查找画板和卡片，类似于 Milanote 中的搜索图标。
get_board	读取	GET /boards/{board_id}	获取画板上的所有卡片：笔记、链接、图片、文件、待办清单、列和子画板。
create_board	写入	POST /boards	在主页上创建新画板，或在另一个画板内创建嵌套画板。
rename_board	写入	PATCH /boards/{board_id}	更改画板标题。
duplicate_board	写入	POST /boards/{board_id}/duplicate	复制画板及其中的所有内容（包括子画板），用作模板。
export_board	读取	GET /boards/{board_id}/export	将画板导出为 Markdown、纯文本、Word、PDF 或 PNG，效果与「导出」菜单相同。

卡片

工具	访问权限	REST 路由	功能说明
add_note	写入	POST /boards/{board_id}/notes	创建纯文本便签卡片，并将其添加到看板的未整理面板。
edit_note	写入	PATCH /boards/{board_id}/notes/{card_id}	替换便签卡片的文本。
add_link	写入	POST /boards/{board_id}/links	创建网页地址的链接卡片，附带网页标题和预览，并将其添加到未整理面板。
add_todo_list	写入	POST /boards/{board_id}/todo-lists	创建待办清单卡片，其中包含任务；每项任务都可以设置可选的截止日期和时间，并将其添加到未整理面板。
set_task_done	写入	PUT /boards/{board_id}/cards/{card_id}/tasks/{task}/done	勾选或取消勾选待办清单中的一项任务。
add_column	写入	POST /boards/{board_id}/columns	在看板上创建空列，用于将卡片归类成一组。

整理卡片

工具	访问权限	REST 路由	功能说明
move_card	写入	POST /boards/{board_id}/cards/{card_id}/move	将卡片或子看板移到另一个看板，或移入、移出某一列。
set_card_color	写入	PUT /boards/{board_id}/cards/{card_id}/color	为便签、待办清单、链接、文件或列顶部的色条设置颜色，或清除颜色。
add_label	写入	POST /boards/{board_id}/cards/{card_id}/labels	为卡片添加标签；如果标签名称不存在，则创建该标签。
list_labels	读取	GET /labels	列出可添加到卡片的标签及其名称和颜色。

回收站

工具	访问权限	REST 路由	功能说明
trash_cards	写入	POST /boards/{board_id}/cards/trash	将卡片或子看板移至回收站，效果与按 Delete 键相同。
list_trash	读取	GET /trash	列出移至回收站的卡片和看板，以及它们原先所在的看板。
restore_card	写入	POST /trash/{card_id}/restore	将卡片或看板移出回收站，并放回原处。

评论

工具	访问权限	REST 路由	功能说明
add_comment	写入	POST /boards/{board_id}/comments	在看板上发布评论卡片，或在评论串中回复；评论将显示在你的名字下。
edit_comment	写入	PATCH /boards/{board_id}/comments/{comment_id}	替换你所写评论的文本。
delete_comment	写入	DELETE /boards/{board_id}/comments/{comment_id}	删除你所写的评论，所有人都无法再看到。

共享

工具	访问权限	REST 路由	功能说明
get_sharing	读取	GET /boards/{board_id}/sharing	查看谁可以打开看板：所有者、编辑者，以及只读链接及其设置。
invite_editor	写入	POST /boards/{board_id}/editors	通过电子邮件邀请他人编辑看板及其中的看板。
remove_editor	写入	DELETE /boards/{board_id}/editors	撤销某人访问看板的权限，或取消对方尚未接受的邀请。
publish_board	写入	POST /boards/{board_id}/publish	启用看板的只读链接，任何人都可以通过该链接打开看板，无需注册。
unpublish_board	写入	DELETE /boards/{board_id}/publish	停用看板的只读链接；拥有该链接的人将无法再打开看板。

账户

工具	访问权限	REST 路由	功能说明
get_usage	读取	GET /usage	查看账户中各类卡片的数量，以及与免费方案限额相比的使用情况。

此版本未提供

工具	原因
upload_image	托管版本通过 Cotlet 的文件处理功能，以链接、上传文件或 base64 的形式接收图片；此代码库目前还不支持该功能。请在 Milanote 中上传图片，或使用托管工具。

我们有意从未实现：Milanote 登录、电子邮件、密码和个人资料设置，以及方案和账单管理。

配置

变量	默认值	作用
MILANOTE_MCP_HOME	~/.config/milanote-api-mcp	session.json 所在文件夹。
MILANOTE_AUTH_TOKEN		Milanote 的 __Secure-milanote.session_token Cookie，用于替代 milanote-mcp connect。
MILANOTE_PROXY		向 Milanote 发出的所有请求使用的代理，例如 http://user:pass@host:port。
MILANOTE_MCP_READ_ONLY		1 会隐藏并拒绝所有会修改 Milanote 的工具（等同于 --read-only）。
MILANOTE_MCP_TOKEN		serve 所需的 Bearer 令牌；要监听 127.0.0.1 以外的地址时必须设置。
MILANOTE_MCP_HOST、MILANOTE_MCP_PORT	127.0.0.1、8787	serve 的地址。

安全与 Milanote 账户

• 你的密码不会进入此代码。 这里只读取 Cookie，且仅限 milanote.com 的 Cookie。
• 会话文件由你保管。 session.json 会以 0600 模式创建。任何拿到此文件的人都可以使用你的身份操作 Milanote，因此请勿将它放入 git 或共享文件夹。
• 默认仅限本地访问。 serve 绑定到 127.0.0.1，若未设置 MILANOTE_MCP_TOKEN，则拒绝绑定到其他地址。
• 仅限 milanote.com。 请求和重定向到 milanote.com 以外地址时会被拒绝。
• 只读模式。 --read-only 或 MILANOTE_MCP_READ_ONLY=1 仅公开 9 个读取工具。
• 有些操作会影响其他人。 评论会显示你的姓名，invite_editor 会向你邀请的人发送邮件，而 publish_board 会让任何拥有链接的人都能查看看板。MCP 客户端会在执行这些操作前征求同意；脚本不会。
• 移至废纸篓的内容可以恢复，评论则不能。 trash_cards 会将卡片移至看板的废纸篓，restore_card 会将它们恢复。delete_comment 会删除所有人都能看到的评论。

错误

REST API 返回 {"error": "<code>", "message": "..."}。MCP 服务会将相同的代码和消息作为工具错误返回。

状态码	代码	处理方法
401	auth_required、auth_expired	没有会话，或 Milanote 已将你登出。请在 Chrome 中登录 Milanote，然后运行 milanote-mcp connect。
403	scope_denied	服务以只读模式运行。
403	target_blocked	Milanote 拒绝了请求，或显示了机器人验证。请在 Chrome 中打开一次 app.milanote.com，然后重试。
422	invalid_input	某个参数缺失或有误；消息会指出具体参数。
429	rate_limited	Milanote 正在限制该账户的请求。请等待几分钟。
502	target_error	Milanote 返回了错误，例如免费套餐的卡片数量限制，或其应用发生了变化。若我们已修复，请运行 git pull 获取最新工具，或提交问题。
504	timeout	Milanote 未能及时确认更改。重试前请检查看板，因为更改可能已经生效。

自托管或托管版

	此仓库	Cotlet，托管版
工具	30 个	31 个，包含 upload_image
运行方式	在你的电脑上运行，电脑开机时可用	在云端全天候运行
Milanote 会话	使用你的 Chrome，Cookie 保存在本地文件中	在欧盟使用你自己的 Cloud Browser，配置文件采用 AES-256-GCM 加密
Milanote 更改其应用时	我们修复后运行一次 git pull	为你修复，每天测试所有工具
审批	你的 MCP 客户端会在每次调用前征求同意	评论、邀请、发布和移至废纸篓等操作会等待你的确认，可按工具切换
兼容对象	你电脑上的 MCP 客户端、本地脚本	Claude.ai 和 ChatGPT 连接器、n8n、Make、Zapier，以及任何 HTTP 客户端
适用对象	你自己，仅限非商业用途	团队、企业、代理机构
价格	免费	免费试用 7 天，含 2,000 点数，无需绑定银行卡；之后可购买一次性点数包，5,000 点数起价 $29

在托管版中，成功调用会消耗 20 至 30 点数（大多数工具为 25 点数），失败调用免费；启用了 Agent 应用的 Cloud Browser 每天会消耗 50 点数。完整定价。

常见问题

Milanote 有官方 API 吗？ 没有。Milanote 没有公共 API、没有 Webhook，也没有官方 MCP 服务（截至 2026 年 10 月已核实）。公共 API 和 MCP 服务是其公开路线图上待实现的功能，目前导出内容的唯一方式是使用“导出”按钮，而且一次只能导出一个看板。详情：cotlet.dev/integrations/milanote-api-mcp-server。

有适用于 Claude、ChatGPT 或 Cursor 的 Milanote MCP 服务吗？ 有，这个服务运行在你的设备上：Claude Code、Claude Desktop、Cursor 和 Codex 可使用 milanote-mcp mcp。ChatGPT 和 Claude.ai 连接器需要公共 HTTPS URL，托管的 Milanote MCP 服务 可提供该 URL。

我可以将 Milanote 看板导出为 Markdown 吗？ 可以，也支持子看板：python examples/export_boards.py --board <board URL> --dir ./outline 会为每个看板写入一个 Markdown 文件，并按嵌套结构存放在相应文件夹中。Word、PDF、PNG 和纯文本也同样支持，只需使用 --format。

我可以备份所有看板吗？ 在 cron 中对 Home 中的每个看板运行 export_boards.py。看板中的图片和文件仍保留在 Milanote 中。使用 Milanote 自带的“导出”菜单中的“生成 ZIP”，即可下载原始文件。

我可以向别人分享给我的看板中添加内容吗？ 可以，只要你的账户有权编辑该看板。只读看板可以查看和导出，但不能修改。

免费方案可以使用吗？ 可以。免费方案的 100 张卡片限制仍然适用：get_usage 会显示当前使用情况，超出限制后添加卡片会失败，并显示 Milanote 自己的提示信息。

为什么需要我的 Chrome？ 为了在不使用密码的情况下读取你的 Milanote 会话，以及读取用于截止日期的时区。每次登录时会使用一次 Chrome，而不是每次调用都使用。

Milanote 将我登出后会发生什么？ 调用会因 auth_expired 失败。如果 Chrome 开启了远程调试，服务会在下次调用时读取新的 Cookie（Chrome 提示时点击“允许”）；否则，请再次运行 milanote-mcp connect。

可以在 VPS 或 Docker 中运行吗？ 技术上可以，使用 MILANOTE_AUTH_TOKEN 即可。但这样一来，Milanote 会看到你的会话来自数据中心 IP，这不太像是你的正常使用环境。若要始终在线，可使用托管版本，它会将你的会话保存在你自己的固定 IP 云浏览器中。

我的 Milanote 账户会被封禁吗？ 请求会携带 Chrome 的指纹信息，并逐个发出，就像你亲自点击一样。没人能保证平台永远不会采取措施。请保持正常使用。

我可以在工作中或为客户使用吗？ 不可以，许可证仅允许非商业用途。团队、公司或客户项目请使用 Cotlet，或发送邮件至 [email protected]。

它是开源的吗？ 源代码是公开的，但许可证并非开源许可证：仅限非商业用途，不得用于商业活动。

某个工具出故障了，或者我需要另一个工具。 请提交问题，并注明工具名称和错误信息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

• **允许：**非商业用途：你出于个人目的使用自己的 Milanote 账户，或由慈善机构、学校、公共研究机构或政府机构使用。可以修改代码，并以相同许可证分享。
• **不允许：**任何商业用途，包括经营自己的业务；客户项目；销售或提供该项目，或基于该项目构建的服务。

---

由 Cotlet（@cotletdev）维护。Milanote 是其所有者的商标。本项目为非官方项目，与 Milanote 无关联，也未获其认可或赞助。