内容
# Kika Obsidian MCP
[](https://github.com/aka-kika/kika-obsidian-mcp/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://obsidian.md/)
[](https://openai.com/codex/)
[](#安全功能)
[](LICENSE)
用于直接与Obsidian知识库中的Markdown文件交互的本地MCP服务器。
- 无需Obsidian插件
- 无需API密钥
- 无需云服务
- 无需在后台运行Obsidian
本项目适用于希望MCP客户端直接与磁盘上的Markdown文件交互的用户。
> 独立的开源项目。 与Obsidian、Anthropic、OpenAI或任何MCP客户端无关。
## 功能
它允许MCP客户端与您的知识库交互，以：
- 读取和搜索笔记
- 创建和更新笔记
- 生成摘要、状态报告和发布笔记
- 自动化本地知识工作流
所有操作都直接针对本地的Markdown文件。
## 适用场景
- 希望安全地本地访问Obsidian知识库的Codex用户
- Claude Desktop、Cline、Cursor等可以运行本地Python服务器的MCP客户端
- 更喜欢基于文件系统的Obsidian自动化而不是本地REST API插件的开发者
- 个人知识库、项目日志、日常笔记、任务笔记和基于Markdown的工作流
## 存在原因
已经有几个Obsidian MCP服务器。许多服务器依赖于Obsidian本地REST API插件或作为Obsidian插件运行。本项目故意简化：
- 直接访问本地知识库文件系统
- 无网络调用
- 无Obsidian API令牌
- Codex友好的TOML配置
- 容忍具有不完美前置信息的现实知识库
- 路径遍历保护，以防止工具逃离配置的知识库
- 可选的只读模式，用于更安全的审查/搜索工作流
- 可选的写入前备份
## 比较
| 需求 | 本项目 |
| --- | --- |
| 与Codex一起使用Obsidian | 是，附带`~/.codex/config.toml`示例 |
| 与Claude Desktop一起使用Obsidian | 是，附带JSON配置示例 |
| 需要Obsidian插件 | 否 |
| 需要API密钥 | 否 |
| 需要Obsidian运行 | 否 |
| 直接读写Markdown文件 | 是 |
| 通过远程HTTP API工作 | 否，仅本地stdio MCP |
## 安全功能
设计为在不鲁莽的情况下仍然有用：
- 只读模式，拒绝写入
- 写入前备份模式，在更新和删除之前
- 知识库路径隔离
- 路径遍历保护
- 无外部网络调用
## 工具
- `configure_vault` - 设置或更改知识库路径
- `get_note` - 按知识库相对路径读取单个Markdown笔记
- `create_note` - 创建带有可选元数据的新的Markdown笔记
- `update_note` - 更新笔记内容和/或前置信息
- `delete_note` - 删除Markdown笔记
- `list_notes` - 列出知识库或文件夹中的笔记
- `search_notes` - 搜索笔记标题、内容和标签
- `get_all_tags` - 从前置信息和内联标签中列出唯一标签
- `get_backlinks` - 查找链接到某个笔记的笔记
- `get_note_links` - 从笔记中提取维基链接
- `create_folder` - 在知识库中创建文件夹
- `get_folder_structure` - 返回知识库文件夹树
## 演示
短启动剪辑：
[Obsidian + MCP + Codex 演示](assets/obsidian-mcp-codex-demo.mp4)
有用的后续演示记录：
- AI在知识库中编辑笔记，然后Obsidian显示结果
- 只读和写入前备份行为
## 快速开始
### 安装
要求：
- 推荐Python 3.10或更新版本
- 存储为本地Markdown文件的Obsidian知识库
```bash
git clone https://github.com/aka-kika/kika-obsidian-mcp.git
cd kika-obsidian-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```
与您的知识库进行验证：
```bash
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python test_server.py
```
## Codex 配置
将以下内容添加到 `~/.codex/config.toml` 并重启Codex：
```toml
[mcp_servers.kika-obsidian]
command = "/absolute/path/to/kika-obsidian-mcp/.venv/bin/python"
args = ["/absolute/path/to/kika-obsidian-mcp/server.py"]
enabled = true
[mcp_servers.kika-obsidian.env]
OBSIDIAN_VAULT_PATH = "/absolute/path/to/your/obsidian-vault"
OBSIDIAN_READ_ONLY = "false"
OBSIDIAN_BACKUP_ON_WRITE = "true"
```
对于更安全的只读设置：
```toml
OBSIDIAN_READ_ONLY = "true"
```
## Claude Desktop 配置
将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"obsidian": {
"command": "/absolute/path/to/kika-obsidian-mcp/.venv/bin/python",
"args": ["/absolute/path/to/kika-obsidian-mcp/server.py"],
"env": {
"OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/obsidian-vault",
"OBSIDIAN_READ_ONLY": "false",
"OBSIDIAN_BACKUP_ON_WRITE": "true"
}
}
}
}
```
## 环境
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `OBSIDIAN_VAULT_PATH` | 是 | 无 | 知识库文件夹的绝对路径。 |
| `OBSIDIAN_READ_ONLY` | 否 | `false` | 当为true时，创建/更新/删除/文件夹创建工具拒绝写入。 |
| `OBSIDIAN_BACKUP_ON_WRITE` | 否 | `false` | 当为true时，在更新/删除之前将现有笔记复制到 `.obsidian-mcp-backups/`。 |
## 安全模型
- 所有笔记路径都相对于 `OBSIDIAN_VAULT_PATH` 解析。
- 拒绝绝对路径和 `../` 路径遍历。
- 可以通过设置 `OBSIDIAN_READ_ONLY=true` 禁用写入。
- 可以通过设置 `OBSIDIAN_BACKUP_ON_WRITE=true` 在更新/删除之前将现有笔记复制到 `.obsidian-mcp-backups/`。
- 只能删除Markdown笔记。
- 服务器不进行外部网络调用。
- 破损的YAML前置信息不会破坏列表/搜索；笔记仍然可以以空元数据读取。
## 开发
运行本地测试脚本：
```bash
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python test_server.py
```
启动MCP服务器：
```bash
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python server.py
```
## 可选自动化
从知识库中生成每日项目状态报告：
```bash
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python scripts/daily_status_report.py --folder "Projects"
```
将报告写回Obsidian：
```bash
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python scripts/daily_status_report.py \
--folder "Projects" \
--write "Codex/Daily Project Status.md"
```
脚本报告最近的笔记、Markdown复选框任务和顶级标签。在更新现有报告笔记时使用写入前备份。
## 常见工作流
参见 [docs/common-workflows.md](docs/common-workflows.md) 获取实用示例：
- 安全的知识库探索
- 项目跟进
- 每日状态报告
- 发布笔记
- 知识库分类
- 索引笔记创建
- 查找链接不足的笔记
- 安全编辑检查清单
## 模板
可复制的Obsidian笔记模板位于 [docs/templates](docs/templates)：
- [Codex 工作日志](docs/templates/codex-work-log.md) 用于每日项目状态和工作流总结
- [项目会话日志](docs/templates/project-session-log.md) 用于每个项目的会话笔记、决策、链接和下一步骤
- [周回顾](docs/templates/weekly-review.md) 用于成就、未完成的事项和下周优先级
## 可选技能
本仓库包含轻量级代理工作流技能：
```text
skills/obsidian-vault-workflow/SKILL.md
skills/release-note-captain/SKILL.md
```
将它们用作与此MCP服务器合作的代理的指导。它们涵盖了安全知识库探索、编辑纪律、每日状态报告、知识库分类、项目跟进提示和发布笔记捕获。
## 常见问题
### 这是一个Obsidian MCP服务器吗？
是的。它是一个用于Obsidian知识库的本地MCP服务器。它为笔记、标签、反向链接、维基链接、文件夹、搜索和可选写入提供了工具。
### 它与Codex一起工作吗？
是的。主要的设置路径是Codex优先的，并使用 `~/.codex/config.toml`。
### 它需要Obsidian本地REST API插件吗？
不需要。它直接从知识库文件夹读取和写入Markdown文件。
### Obsidian需要运行吗？
不需要。因为此服务器处理本地文件，因此无需打开Obsidian。
### 我可以使其只读吗？
是的。设置 `OBSIDIAN_READ_ONLY=true` 以允许搜索和检查，同时拒绝创建、更新、删除和文件夹创建工具。
## 当前限制
- 搜索是简单的子字符串搜索，而不是语义或索引搜索。
- 无Obsidian命令面板或插件API访问。
- 无冲突解决同时编辑的功能。
- 无模板扩展。
- 无同步提供程序感知。
## 许可证
MIT
