Obsidian MCP — hardened Codex integration

Obsidian Local REST API 5.2.0 的隐私安全发行版，包含原生 Streamable HTTP MCP 服务、可移植 Codex 插件清单和默认只读工具配置。它适合让 Codex 在本机检索、读取和理解 Obsidian Vault，同时把认证信息与 Vault 内容保留在用户设备中。

English summary: a privacy-sanitized, read-first Codex package for Obsidian Local REST API with MCP. The public repository contains source and configuration templates only—never a user's vault, API key, certificates or plugin data.json.

为什么需要这个发行版

上游插件提供成熟的 REST/MCP 能力。本仓库在固定上游版本之上增加公开部署所需的安全层：

• Codex 标准 .codex-plugin/plugin.json 与 .mcp.json；

• API key 仅通过 OBSIDIAN_MCP_API_KEY 注入；

• MCP 地址固定为 127.0.0.1 回环接口；

• 默认只开放 8 个读取、检索和结构查看工具；

• 不分发 data.json、证书、私钥、Vault 内容或用户路径；

• 删除自动发布/文档部署工作流，只保留只读权限 CI；

• 明确记录上游版本、commit、改动与许可证归属。

Related MCP server: obsidian-mcp-server

默认工具

写入、移动、删除、命令执行、二进制上传和签名 URL 工具不在默认 allowlist。需要这些能力时，应逐项审查、由用户明确授权后再单独启用。

架构

Codex / MCP client
       │  Bearer token from environment
       ▼
http://127.0.0.1:27123/mcp/
       │
       ▼
Obsidian desktop plugin
       │
       ├── authentication
       ├── vault path containment
       ├── MCP annotations
       └── Obsidian vault adapter

详见 docs/architecture.md。

项目结构

obsidian/
├── .codex-plugin/plugin.json  # Codex 插件元数据
├── .mcp.json                  # 不含密钥的回环 MCP 配置
├── skills/obsidian/SKILL.md   # 读取优先的使用规则
├── src/                       # 上游 TypeScript 插件源码
├── scripts/                   # 构建、文档与安装辅助脚本
├── docs/                      # API 与安全架构文档
├── manifest.json              # Obsidian 插件清单
├── package.json               # Node 22 构建与测试入口
└── LICENSE / NOTICE.md

环境要求

• Obsidian Desktop 1.13.1 或更新版本；

• Node.js 22；

• Codex 插件环境或其他支持 Streamable HTTP MCP 的客户端；

• Windows、macOS 或 Linux 本机环境。

构建与安装

git clone https://github.com/ZNaiGaomu/obsidian.git
Set-Location .\obsidian
npm ci
npm run build

把 main.js、manifest.json 和 styles.css 放入目标 Vault 的：

.obsidian/plugins/obsidian-local-rest-api/

Windows 用户也可以明确指定测试 Vault：

pwsh -File .\scripts\install-codex-build.ps1 -VaultPath 'D:\Obsidian\DisposableVault'

脚本不会读取或写入 API key。启用插件后，在 Obsidian 设置中生成自己的 key，并把它放入当前用户环境，而不是项目文件：

$env:OBSIDIAN_MCP_API_KEY='<your-own-key>'

不要把真实值写入 .env.example、.mcp.json、Codex 技能或 Git 提交。

Codex 配置

仓库中的 .mcp.json 默认 enabled: false。完成以下检查后再启用：

1. Obsidian 插件版本为 5.2.0-hardened.1；

2. 服务仅监听 127.0.0.1:27123；

3. OBSIDIAN_MCP_API_KEY 已在本机设置；

4. 使用 disposable Vault 验证读取工具；

5. 确认没有额外写入工具被意外加入 allowlist。

测试

npm ci
npm run lint
npm test
npm run typecheck
npm run build

本发行基线曾通过 822 项测试、TypeScript 类型检查、生产构建及零生产依赖漏洞审计。该记录描述固定源码快照，不替代下载者在自身 Node/Obsidian 环境中的复测。

上游与版本

• Upstream: coddingtonbear/obsidian-local-rest-api

• Tag: 5.2.0

• Commit: ca20f7d783c191e2ea8a3474b99de9f175e9f219

• Hardened release: 5.2.0-hardened.1

上游完整说明保存在 docs/upstream-readme.md。修改记录见 CHANGELOG.md。

安全与许可证

源码遵循上游 MIT License，归属说明见 NOTICE.md。安全报告和默认权限边界见 SECURITY.md。本项目不是 Obsidian 官方产品。