Margins

margins-mcp

在 Obsidian 知识库中使用你的 Claude Pro/Max 订阅。 无需 API 密钥。没有按 token 计费。无需嵌入流水线。Claude 会读取你的笔记并提出更新建议；推理费用由你的订阅支付；文件仍保存在你的磁盘上。

margins-mcp 是一个小型 Node 程序，位于 Claude（Desktop 或 Code）与 Obsidian 知识库之间。你与 Claude 聊天时，它会通过 margins-mcp 读取笔记。文件保存在本地，由 Claude 负责思考，费用由你现有的订阅支付。

你属于哪种 Margins 用户？

Margins 适用于六种常见的起步情况。首次调用时，margins_start 会自动检测你的状态，因此你无需自行分类——不过，了解自己属于哪一行有助于建立合理预期。

你……	用户类型	首次对话
使用 Obsidian，知识库已用 wikilinks 整理	A1	针对笔记进行问答。调用 margins_start 后即可提问。
使用 Obsidian，知识库为空或刚建立	A2	请 Claude 搭建日记和会议模板。
使用 Obsidian，文件很多，但 wikilinks 很少	A3	在某个页面上运行 propose_wikilinks，找出你遗漏的关联。
不使用 Obsidian，但有整理好的 Markdown 文件	B1	与 A1 相同。安装 Obsidian，以便使用提案审核界面。
不使用 Obsidian，文件夹为空	B2	使用 --starter-vault ~/Margins 搭建一个知识库。
不使用 Obsidian，文件夹杂乱	B3	在最繁忙的页面上运行 propose_wikilinks。安装 Obsidian，以可视化方式审核提案。

要求

• Node.js 18 或更新版本
• 一个 Obsidian 知识库，或任何包含笔记、PDF、Office/OpenDocument 文件、电子邮件导出文件、EPUB 或纯文本的文件夹
• Claude 订阅：Pro（20 美元/月）、Max 或 Claude Code

安装

只需两条命令：

npm install -g margins-mcp
margins-mcp install

安装程序会提示你输入知识库路径，检测 Claude Desktop 和 Claude Code，写入相应的配置文件；如果知识库中缺少 raw/、proposed/ 和 .margins/，还会创建这些目录，并运行验证探测。重启 Claude Desktop（在 macOS 上按 Cmd-Q，不要只关闭窗口）；或者在 Claude Code 中运行 /mcp，确认列表中显示 Margins。

还没有知识库？

搭建一个符合 Margins 结构的知识库：

margins-mcp install --starter-vault ~/notes

查找 Obsidian 知识库路径

如果你已经在使用 Obsidian，但不知道知识库的绝对路径：

• **在 Obsidian 中：**在文件树中右键点击知识库名称 →“在 Finder 中显示”（macOS）或“在文件资源管理器中显示”（Windows）。路径会显示在标题栏中。
• macOS 常见路径：~/Documents/<VaultName>；如果使用 iCloud 同步，则为 ~/Library/CloudStorage/iCloudDrive/Obsidian/<VaultName>。
• Linux 常见路径：~/Documents/<VaultName> 或 ~/.local/share/Obsidian/<VaultName>。
• Windows 常见路径：%USERPROFILE%\Documents\<VaultName>。

通过 --vault /absolute/path 将路径传给安装程序，或按提示输入。

不安装即可试用

npx margins-mcp install --vault /path/to/vault

你会看到一条警告：npm 可能会清理 npx 缓存，导致配置在几周后失效。正式使用时，建议优先采用上面的 npm install -g。使用 npx 试用则没有问题。

手动安装

如果你更愿意自行编辑配置，请将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS；Windows/Linux 路径请参见 Anthropic 文档）：

{
  "mcpServers": {
    "margins": {
      "command": "node",
      "args": ["/absolute/path/to/margins-mcp/bin/margins-mcp.js"],
      "env": { "MARGINS_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

试试看

在新的 Claude 对话中询问：

使用 margins，总结一下我最近的笔记。

或者：

哪些页面支持“我的项目截止日期是 May 30th”这一说法？使用 margins 帮我找到它们。

或者：

我刚把一个电子表格放进了 raw/。请将它整理成 wiki 中结构化的来源页面。

模型可以读取你的知识库、提出新建页面的建议、提出修改现有页面的建议，也可以将原始来源整理为结构化的 wiki 页面。propose_compile_from_raw 接受 Markdown/纯文本、PDF、Word 文档、电子表格、演示文稿、电子邮件导出文件、EPUB、OpenDocument 文件、RTF、HTML、CSV/TSV、JSON、YAML 以及常见的文本类格式。所有写入操作都会先暂存到 proposed/；只有你接受后，内容才会写入。

工具

上下文（每次对话调用一次）

工具	用途
margins_start	Vault 统计信息 + 待处理提案 + 尚未摄取的原始文件 + 最近的偏好设置，以及 Vault 中的 CLAUDE.md（如果存在）。作为 Claude 整个对话的依据。
recall_preferences	从 .margins/preferences.md 中读取持久化的用户偏好（归档约定、命名模式、此前的修正）。Claude 会在提出任何提案前调用此工具。

读取

工具	用途
search_vault	在整个 Vault 中进行全文和文件名搜索。
read_page	按相对路径读取一个页面。
list_recent	最近修改的页面。
get_backlinks	通过 Wikilink 指向目标 slug 的页面。
search / fetch	兼容 ChatGPT Deep Research 的工具对。

提议写入（暂存——接受前不会写入）

工具	用途
propose_page	在 proposed/<path> 下暂存新页面。
propose_edit	暂存字符串替换编辑。before 必须恰好出现一次。
append_to	暂存追加内容。如果页面不存在则创建；并接续待处理提案。
propose_compile_from_raw	将 raw/ 中的原始转录、笔记、PDF、Word 文档、电子表格、演示文稿、电子邮件、EPUB 或其他受支持的文档转换为结构化源页面。
list_proposals	列出待处理提案，以及每条提案的覆盖风险标记。
resolve_proposal	action: "accept" 会写入提案；action: "reject" 会丢弃提案。

建议（适用于文件多、链接少的 A3 / B3 Vault）

工具	用途
propose_wikilinks	扫描页面中的实体类短语，并提议添加指向 Vault 中具有相同 slug 的其他页面的 Wikilink。随后，模型会连续调用 propose_edit，应用它认可的链接。

学习

工具	用途
record_preference	将持久规则追加到 .margins/preferences.md。当用户以应适用于后续操作的方式（如归档路径、命名、摘要长度等）修正提案时，Claude 会调用此工具。

提案流程的工作方式

每个写入工具都会将内容暂存到 Vault 内的 proposed/<path>。在你（或代表你操作的 MCP 客户端）调用 resolve_proposal 并设置 action: "accept" 之前，不会有任何内容写入正式文件树。你也可以检查暂存内容（ls proposed/），并自行移动文件以接受提案。

连续编辑会叠加：对同一路径进行第二次 propose_edit 时，会读取待处理提案，而不是 Vault 中的内容。

配置

环境变量	默认值	用途
MARGINS_VAULT	（必需）	Obsidian Vault 或 Markdown 文件夹的绝对路径。
MARGINS_INDEX_ROOTS	自动检测	以逗号分隔的待索引子文件夹。自动检测规则：存在 .obsidian/ → 索引根目录；存在 wiki/ → 仅索引 wiki/；两者都不存在 → 索引根目录。
MARGINS_TELEMETRY	（同意文件）	覆盖遥测设置：on 或 off。默认使用安装期间作出的同意决定。

Margins 不是什么

为了明确范围：

• 不是推理层。 这部分由你的 Claude 订阅付费。Margins 不会调用任何大模型。
• 不是 Web 应用。 聊天界面位于 Claude Desktop / Claude Code / claude.ai 中。Margins 只是底层连接设施。
• 不是云同步。 本地优先。你的文件会保留在本地磁盘上。
• 不是 CRM 集成。 这是不同的产品。
• 不基于 API 密钥。 订阅透传正是它的核心。

隐私

• Vault 内容绝不会离开你的设备。Margins 是一个 Node 进程，会在本地读写文件，并通过 stdio 暴露结构化工具。
• 匿名遥测（安装时选择加入）会报告工具调用次数，帮助我确定接下来要开发什么。示例事件载荷：GET https://margins.goatcounter.com/count?p=/tool/search_vault。不会收集任何 Vault 内容、文件路径，也不会收集标准的 24 小时滚动会话令牌（由 GoatCounter 分配）以外的用户标识符。可通过 MARGINS_TELEMETRY=off 按会话禁用。选择记录保存在 ~/.margins/consent.json。

开发

git clone https://github.com/cflorczyk9/Margins.git
cd Margins
npm install
npm test
MARGINS_VAULT=/path/to/test/vault npm start

编译器（src/compiler/）最初从早期的 Margins Web 应用中引入。Web 应用及其落地页位于此仓库的 legacy-webapp 分支。如果需要从该分支拉取更新，可使用 scripts/vendor-compiler.sh 重新引入。

Margins 如何随着时间变得更智能

两方面会相互叠加：

1. 你的 Vault 中的 CLAUDE.md 会由 margins_start 自动加载。在其中添加 Vault 专属规则——归档约定、语气、命名模式——Claude 就会在每次对话中遵守这些规则。无需复制粘贴。
2. .margins/preferences.md 是 Margins 在你的 Vault 中维护的文件。当你纠正 Claude（“不，这应该放在 projects，而不是 personal”）时，Claude 会调用 record_preference 记住这条规则。下次对话时，它会在提出写入建议前，通过 recall_preferences 读取这些规则。该文件是纯 Markdown——你可以审查、手动编辑，也可以删除不再适用的部分。

这两个文件都保存在 Vault 中，因此会随 Vault 一起迁移。更换设备、更换宿主端（从 Claude Desktop 切换到 Claude Code，再到 ChatGPT，等该功能上线后），你的约定都会随之迁移。

路线图

• v0.6：在 marginsmcp.com 提供 Web 入门流程——通过 File System Access 选择文件夹、搭建 Vault，并获取安装命令。无需熟悉命令行即可满足 B2/B3 用户画像的需求。
• v0.6：get_citations（语义嵌入搜索，可选择安装依赖项）。
• v0.6：为 propose_compile_from_raw 增加 OCR/图像、旧版 Office 二进制文件及音频/视频内容的导入。
• v0.7：为 claude.ai 网页版和 ChatGPT 自定义连接器提供 HTTP / Streamable 传输方式。
• v0.7+：如果有足够的需求信号，则在 MCP 之外推出 Obsidian 社区插件。
• v0.8+：文件监视器／将文件放入 raw/ 时自动搭建。

许可证

MIT