Markpin

@markpin/mcp

用于 Markpin 文件夹的 MCP 服务。Markpin 是一款 Chrome 扩展，可将网页和剪藏内容保存为 Markdown 文件，存储在你自己的文件夹中——此服务让 AI 客户端（Claude Code、Claude Desktop、Cursor 等）能够搜索和读取这些文件，也可以在你确认后进行编辑。

• 默认只读。写入需要使用 --allow-write，且每次更改都需要通过确认对话框。
• 在本地通过 stdio 运行。任何内容都不会离开你的电脑。
• 会监视文件夹，因此你在浏览器中保存的网页无需重启，就会在下一次查询中显示。

要求

• Node.js 20.1 或更高版本（node -v）。
• 安装 Markpin Chrome 扩展，并将存储位置设为 Local folder 或 Google Drive。如果使用 Google Drive，还需要安装 Google Drive for Desktop，以确保文件夹存在于磁盘上。

运行

npx -y @markpin/mcp --dir "<your Markpin folder>"

选项：

标志	含义
--dir <path>	必填。Markpin 文件夹（包含 pages/ 的文件夹）。~ 会展开。
--allow-write	注册 10 个写入工具。不使用此选项时，服务为只读。
--lang ko|en|ja|es|pt-BR|de|fr	确认对话框的语言。默认值：根据系统区域设置确定（pt* → pt-BR），否则为 en。Markpin 扩展的设置指南会根据你的 Chrome 语言填写此项。

成功后，服务会将 serving N pages from <dir> 写入 stderr。stdout 用于 MCP 协议，因此所有日志都会写入 stderr——这行信息是最快检查路径的方法。

查找 Markpin 文件夹

文件夹必须包含 pages/ 目录。如果没有，说明扩展尚未向其中上传任何内容——请先在 Chrome 中保存一个网页。

Local folder——你在 Markpin 设置中选择的文件夹。

• macOS：在 Finder 中右键点击该文件夹，按住 ⌥ Option，选择 Copy "…" as Pathname。
• Windows：按住 Shift 并右键点击该文件夹，选择 Copy as path（移除首尾的引号）。

Google Drive——Drive for Desktop 会将 Drive 同步到磁盘。Markpin 文件夹位于 My Drive 的顶层，其名称取决于 Google 账号的语言——My Drive (en)、내 드라이브 (ko)、マイドライブ (ja)、Mi unidad (es)、Meu Drive (pt-BR)、Meine Ablage (de)、Mon Drive (fr)：

• macOS：~/Library/CloudStorage/GoogleDrive-<your email>/My Drive/Markpin
• Windows：G:\My Drive\Markpin（盘符可能不同——请在文件资源管理器中查看）

Chrome 中的 Markpin 设置页面有一个 MCP setup guide 按钮，可为你填写这些路径（以及 --lang）。

注册服务

将 <dir> 替换为你的文件夹路径。如果要使用写入工具，请在参数末尾添加 --allow-write。

Claude Code

claude mcp add -s user markpin -- npx -y @markpin/mcp --dir "<dir>"

-s user 会为所有项目注册服务；移除此标志则仅在当前目录中注册。

然后，claude mcp list 应显示 markpin: … - ✓ Connected。

Claude Desktop

编辑配置文件（Claude → Settings → Developer → Edit Config）：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

macOS：

{
  "mcpServers": {
    "markpin": {
      "command": "npx",
      "args": ["-y", "@markpin/mcp", "--dir", "<dir>"]
    }
  }
}

Windows（Claude Desktop 启动时不会使用 shell，因此 npx 需要使用 cmd /c；路径中的反斜杠需要转义）：

{
  "mcpServers": {
    "markpin": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@markpin/mcp", "--dir", "G:\\My Drive\\Markpin"]
    }
  }
}

重启 Claude Desktop。聊天框中的锤子/插头图标会列出 Markpin 工具。

Cursor

将相同的 JSON 添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目），然后在 Cursor Settings → MCP 中启用该服务。

文件格式

每个页面都是一个 Markdown 文件。frontmatter 仅包含面向用户的键（title、url、savedAt、tags、summary、readAt、deletedAt），这样 Obsidian 等笔记应用就能显示简洁的 Properties 面板。Markpin 内部所需的所有内容（id、rev、updatedAt、带锚点的剪藏内容、书签）都存放在文件末尾的一行 JSON 块中：

请勿手动编辑该块。仍会读取在 0.7.0 之前写入的文件（frontmatter 中包含 markpin: 1），下次文件发生任何更改时，会将其重写为新格式。

markpin.json（Markdown 模板）

当你选择 Markdown 模板，或在选项中启用 .trash/ 时，扩展程序会在文件夹根目录写入 markpin.json。此服务会在启动时和每次重新扫描时读取该文件，并使用相同的模板（default 或 obsidian，或自定义模板字符串）渲染其写入的文件，因此通过 MCP 保存的页面看起来会与通过浏览器保存的页面一致。只有 frontmatter 下方的正文会发生变化；frontmatter 始终由 Markpin 管理。将已删除文件移至 .trash/ 由扩展程序完成，而非此服务。

只读与 --allow-write

未使用 --allow-write 时，服务会提供四个读取工具，且无法更改任何文件。使用该选项后，会新增十个写入工具。每次写入都必须通过以下三道关卡：

1. 标志。 你在注册时决定是否允许写入。
2. 客户端权限。 这些工具会标记为非只读（delete_pages 标记为破坏性操作），因此 Claude Code 等客户端会在每次调用前征求确认。
3. 你的确认。 如果客户端支持 MCP elicitation（Claude Code 支持），服务会显示一个说明具体更改的对话框——例如 “向 ‘React Docs’ 添加标签 frontend？”——只有在你接受后才会写入。如果客户端无法显示该对话框，结果中会包含 "gate": "client"，这样助手就能告知你，唯一的确认来自客户端自身的提示。

确认最多等待 10 分钟。只有在你接受后，save_page 才会发起获取请求，因此被拒绝的 URL 永远不会被请求。

工具

读取（始终可用）：

工具	功能
search	对标题、内容、剪藏文本、备注和标签进行全文搜索。查询为空 = 最近内容，可按标签筛选。bookmarked: true = 仅显示带有阅读书签的页面。
get_page	按 ID 或 URL 获取单个完整页面：元数据、标签、摘要、内容、带备注和颜色的剪藏、书签、文件路径和图片路径。
list_recent	最近更新的页面。bookmarked: true = 带有阅读书签的页面，按书签时间从新到旧排序。
list_tags	所有标签及其页面数量。

写入（--allow-write）：

工具	功能
save_page	将 URL 保存为新页面（会抓取并提取文章，除非你传入 content）。可选参数 summary（一到两句话）和 tags——由于 Markpin 内置 AI 只会处理从浏览器保存的页面，因此只要助手读过页面，就会要求助手提供这两项。每个 URL 只对应一个页面——如果页面已存在，则原样返回。
update_tags	为一个或多个页面添加和／或移除标签。
add_clip	向页面添加引用文本剪藏，可选备注、高亮 color（amber、green、blue、pink）和反应标记 kind（question、insight、disagree、star）。
set_clip_note	替换剪藏的备注（留空则清除）。
set_summary	替换页面摘要（留空则清除）。适用于没有摘要的页面。
set_note	设置读者对页面的一行备注（frontmatter note；留空则清除）。
mark_skimmed	将页面标记为已略读（skimmedAt）；同时移除书签和已读标记。
delete_pages	将页面标记为已删除。Markpin 扩展会保留这些页面 30 天，并可恢复；此服务不会删除文件。
restore_pages	恢复过去 30 天内删除的页面。
set_bookmark	为页面添加阅读书签——从开头开始，或在内容中的 quote 处继续阅读。替换任何现有书签，并清除已读标记。
clear_bookmark	移除书签，但不将页面标记为已读。
mark_read	将页面标记为已读并移除书签。

每次写入都会返回 note 和 gate 字段（当你在对话框中确认时为 "elicitation"，只有客户端的提示词在助手和写入之间起到拦截作用时为 "client"）。update_tags、set_clip_note、set_summary 和 set_note 还会返回 before/after；其他工具则返回受影响的页面。

限制

• Google Drive + 新页面。 使用 Google Drive 存储时，扩展只能读取自己创建的文件（drive.file scope），因此 save_page 会将新页面写入 Markpin 文件夹中的 inbox.jsonl，扩展会在下次同步时将其转换为页面文件。该文件由扩展创建和管理——不要删除。对现有页面的编辑会直接写入原文件。使用本地文件夹时，通常不会有收件箱，所有内容都会直接写入；如果文件夹中存在 inbox.jsonl（例如此前的 Drive 镜像），服务也会以相同方式使用它。
• 不支持区域剪藏。 图片／区域剪藏需要页面 DOM；服务只会添加文本剪藏。
• 侧边栏延迟。 侧边栏打开时，每 15 秒轮询一次，因此更改会在约 30 秒内显示；侧边栏关闭时，更改会在你打开它后立即显示。每 5 分钟也会执行一次完整同步。使用 Google Drive 时，还需加上 Drive for Desktop 上传所需的时间。
• 并发编辑。 如果扩展在服务读取页面后写入了同一页面，写入会被拒绝，并显示 自读取以来，磁盘上的页面已更改；请重新读取后重试。请重新尝试。
• 墓碑记录。 删除的页面只能由扩展清除。仅由此服务使用的文件夹会保留这些页面。

故障排除

症状	原因 / 解决方法
Not a directory: …	--dir 中有拼写错误，或 Drive for Desktop 未运行 / 文件夹尚未镜像。请先在 Finder 或 Explorer 中打开该路径。
serving 0 pages	文件夹中还没有 pages/，或该目录为空。在 Chrome 中保存一个页面；如果使用 Drive，请等待上传完成。
客户端提示服务启动失败	运行 node -v（需要 20.1+）。在 Windows 上使用 cmd /c npx 形式。在终端中运行 npx 命令，以查看错误。
刚保存的页面没有显示	文件更改后，服务会在约 300 ms 后重新扫描。如果使用 Drive，等 Drive for Desktop 完成同步后，文件才会显示。
助手保存的页面未显示在侧边栏中	保持侧边栏打开约 30 秒。如果使用 Google Drive，必须运行 Drive for Desktop，才能让 inbox.jsonl 同步到 Drive。
更新 Chrome 扩展程序后页面丢失	文件现在以格式 v2 写入（参见 文件格式）。0.7.0 之前的服务会跳过这些文件——请运行 npx -y @markpin/mcp@latest，或使用当前版本重新注册。
缺少写入工具	注册时未使用 --allow-write。请重新注册，然后重启客户端，使其再次启动服务。
助手保存的页面没有摘要或标签	助手保存页面时没有读取页面内容。请让它撰写摘要和标签（set_summary、update_tags）。
Not an HTML page / 服务无法获取 URL	网站屏蔽了机器人，或需要登录。请让助手自行读取页面，并将 content 传递给 save_page。
User declined / No response to the confirmation	你拒绝了对话框，或对话框在 10 分钟后超时。没有写入任何内容。

开发

yarn build:mcp                 # bundles to mcp-server/dist/index.js
node mcp-server/dist/index.js --dir "<dir>"

许可证：MIT。