Obsidian MCP 81c3fb07

MCP文档知识

提供方 mikesusz

文档知识 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude DesktopClaude
查看接入方式

一个基于前端权限控制的Markdown文件管理系统,适用于Obsidian、Hugo等多种笔记和静态网站生成工具。

一句话选型结论

按资料字段整理

Obsidian MCP 81c3fb07 属于文档知识类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 10 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量10暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

Markdown管理Python本地部署权限控制笔记系统前端权限文件管理

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
python -m venv .venv

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 10 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 10 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Obsidian MCP 81c3fb07当前 10 stdio · 本地进程 本地部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方mikesusz上游标注的维护方 mikesusz
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

16.9 KB
来自项目仓库与上游目录的原文,未做删改

markdown-vault-mcp

Agent-controlled markdown files with frontmatter-based permissions.

Works with Obsidian vaults, static site generators (Hugo, Jekyll, Astro), note-taking apps (Bear, Typora, iA Writer), or any folder of .md files.

Note: if you want a simple, read-only version with no file-write capabilities, see the 1.0 Release.

Quick Start```bash

1. Clone and install

git clone https://github.com/mikesusz/markdown-vault-mcp
cd markdown-vault-mcp
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .

2. Set your markdown folder path

cp .env.example .env

Edit .env and set VAULT_PATH=/path/to/your/markdown/files

3. Add to your MCP client configuration


**MCP Client Config** (Claude Desktop, etc.):```json
{
    "mcpServers": {
        "markdown-vault": {
            "command": "/path/to/markdown-vault-mcp/.venv/bin/python",
            "args": ["-m", "markdown_vault_mcp.server"],
            "env": {
                "VAULT_PATH": "/path/to/your/markdown/files"
            }
        }
    }
}

Use the full path to the Python binary inside your virtualenv. The VAULT_PATH can be set in .env or passed via the client config (client takes precedence).

Requirements

  • Python 3.10+
  • A folder containing .md files

Works With

  • Obsidian — point VAULT_PATH at your vault folder
  • Hugo / Jekyll / Astro — point at your content/ folder
  • Bear / Typora / iA Writer — point at your notes folder
  • Plain markdown — point at any folder of .md files

The server doesn't care about your note-taking app — it just needs markdown files with optional YAML frontmatter.


Permission System

Control agent access with a single frontmatter field. Notes without frontmatter default to append — no configuration files, no hardcoded lists.

Permission Hierarchy

Value Agent can…
hidden Nothing — file is completely invisible
read View but not modify
append Add content only (default if no frontmatter)
edit Full read + write access

Usage

Add agent_access to any note's frontmatter:```yaml

agent_access: edit # or: append, read, hidden


### Tool Requirements

| Tools            | Minimum Permission |
| ---------------- | ------------------ |
| Read operations  | `read`             |
| `append_to_note` | `append`           |
| Edit operations  | `edit`             |

**Read operations:** `get_note`, `search_notes`, `list_notes`
**Edit operations:** `update_note`, `replace_in_note`, `update_section`

Notes with insufficient permissions return a clear error:```
Error: Insufficient permissions. This note has agent_access: 'append',
but this operation requires: 'edit'. Add agent_access: 'edit' to the
note's frontmatter to enable this operation.

Available Tools

search_notes

Search markdown notes by title or content (case-insensitive). Returns up to 10 results with a short excerpt around each match.

Input:

  • query (string, required) — term to search for

Example result:```json
{
"results": [
{
"title": "Meeting Notes",
"path": "work/Meeting Notes.md",
"snippet": "…discussed the new project architecture…",
"relevance_score": 7.0
}
]
}


Plus a `warnings` array if any files had to be skipped.

---

### `get_note`

Retrieve the full content and metadata of a specific note.

**Input:**

- `note_path` (string, required) — path relative to vault root, e.g. `"folder/My Note.md"`

**Example result:**```json
{
    "title": "My Note",
    "path": "folder/My Note.md",
    "content": "# My Note\n\nBody text here…",
    "frontmatter": { "tags": ["idea"], "created": "2024-01-01" },
    "modified": "2024-06-15T10:30:00",
    "size": 1024
}

If the note's frontmatter can't be parsed, get_note returns a structured error naming the problem instead of the note:```json
{
"error": "Could not parse this note's frontmatter",
"detail": "YAML parse error: mapping values are not allowed in this context (line 3)",
"path": "Reference - House.md"
}


---

### `list_notes`

List all markdown notes in the vault (or a subfolder).

**Input:**

- `folder` (string, optional) — subfolder path relative to vault root

**Example result:**```json
{
    "notes": [
        { "title": "Home", "path": "Home.md", "size": 512, "modified": "2024-06-01T09:00:00" },
        {
            "title": "Daily Note",
            "path": "Daily/2024-01-15.md",
            "size": 256,
            "modified": "2024-01-15T08:00:00"
        }
    ]
}

Plus a warnings array if any files had to be skipped.


list_writable_notes

Show all notes that agents can append to — those with agent_access: append or edit, plus notes without any frontmatter (which default to append).

Input: none

Example result:```json
{
"writable_notes": [
{ "path": "__INBOX.md", "access_level": "append" },
{ "path": "projects/status.md", "access_level": "edit" }
]
}


Plus a `warnings` array if any files had to be skipped.

---

### `append_to_note`

Append content to the end of a note. Works on any note with `agent_access: append` or `edit`, or any note without frontmatter. Never overwrites existing content. Creates the file if it doesn't exist yet.

**Input:**

- `note_path` (string, required) — path relative to vault root, e.g. `"inbox.md"` or `"folder/notes.md"`
- `content` (string, required) — text to append
- `add_timestamp` (boolean, optional, default: `true`) — if true, inserts a `## YYYY-MM-DD HH:MM` heading before the content

**Example result:**```json
{
    "success": true,
    "note_path": "inbox.md",
    "appended_content": "\n## 2026-03-24 10:30\nOrder furnace filters\n",
    "message": "Successfully appended to 'inbox.md'."
}

Example usage:

  • append_to_note("inbox.md", "Order furnace filters") — timestamped capture
  • append_to_note("books.md", "- The Expanse", false) — add a list item without a heading
  • append_to_note("new-note.md", "Some content", false) — creates the file if it doesn't exist

list_templates

List all .md files in your vault's templates/ directory.

Input: none

Example result:```json
{
"templates": [
{
"name": "PROJECT",
"path": "templates/PROJECT.md",
"size": 100,
"description": "General project template"
},
{
"name": "JOURNAL",
"path": "templates/JOURNAL.md",
"size": 96,
"description": "Daily journal entry"
}
]
}


Plus a `warnings` array if any files had to be skipped.

---

### Skipped files

Every vault-scanning tool — `list_notes`, `search_notes`, `list_writable_notes`,
and `list_templates` — skips any file it can't read rather than failing the whole
scan. When that happens, it reports the skipped files alongside the normal
results:```json
{
    "notes": [ "…normal results, unchanged…" ],
    "warnings": [
        {
            "path": "Reference - House.md",
            "error": "YAML parse error: mapping values are not allowed in this context (line 3)"
        }
    ]
}
  • The warnings key is absent entirely when nothing was skipped — it never
    appears as an empty array.
  • Each entry carries only the path and the parse error. A note's title, content,
    frontmatter, and access level are never included, since an unparseable note may
    well have been meant to stay hidden.
  • Skipped files are also logged to stderr, visible in your MCP client's logs.
  • Hidden notes (agent_access: hidden) are excluded silently and never appear
    in warnings — that's a deliberate setting, not a problem to report.

create_note_from_template

Create a new note from an existing template. Automatically replaces placeholders like {{TODAY}} and {{AGENT_ACCESS}}, and pre-fills frontmatter or heading-based fields.

Input:

  • template_name (string, required) — name of the template (e.g. "PROJECT", "New Book"). Must match a file in templates/.
  • note_suffix (string, optional) — appended to the filename, e.g. "deck replacement" → "PROJECT deck replacement.md". Letters, numbers, spaces, hyphens, underscores only.
  • field_values (object, optional) — pre-fill template fields. Keys match YAML frontmatter field names (e.g. {"title": "My Book", "authors": "Jane Smith"}). Keys not found in frontmatter will be matched against # KEY: headings in the body instead.
  • agent_access (string, optional) — permission level for agent access after creation: "edit", "append" (default), "read", or "hidden". Overrides any value already in the template's agent_access frontmatter field. Infer from the user's phrasing (see Templates section below).

Example result:```json
{
"success": true,
"file_path": "PROJECT deck replacement.md",
"message": "Created new note from template",
"template_used": "templates/PROJECT.md",
"fields_applied": { "title": "deck replacement" }
}


---

### `update_note`

Replace the entire body of a note with new content. Frontmatter (including `agent_access`) is always preserved. Requires `agent_access: "edit"` in the note.

**Input:**

- `note_path` (string, required) — path relative to vault root, e.g. `"My Note.md"`
- `new_content` (string, required) — full replacement body text

---

### `replace_in_note`

Find and replace a specific piece of text in a note body. Exact match, case-sensitive. Only operates on body content — frontmatter is never touched. Requires `agent_access: "edit"`.

**Input:**

- `note_path` (string, required) — path relative to vault root
- `old_text` (string, required) — exact text to find
- `new_text` (string, required) — replacement text

**Errors:**

- `"Text not found in note: '...'"` — if `old_text` doesn't appear in the body

---

### `update_section`

Replace the content beneath a specific heading, preserving the heading line itself. Content is replaced up to (but not including) the next heading, or end of file. Requires `agent_access: "edit"`.

**Input:**

- `note_path` (string, required) — path relative to vault root
- `heading` (string, required) — exact heading text, e.g. `"## Next Steps"` or `"SYNOPSIS:"`
- `new_content` (string, required) — replacement content for that section

**Errors:**

- `"Heading '...' not found in note"` — if the heading doesn't exist

---

## Templates

### Adding templates

Drop any `.md` file into your vault's `templates/` directory — no configuration needed:```
templates/
├── PROJECT.md
├── New Book.md
├── JOURNAL.md
└── RECIPE.md

Add an optional description comment at the top to make it show up nicely in list_templates:```markdown
%% My recipe template %%


date: "{{TODAY}}"
source: ""


TITLE:

SOURCE:

Ingredients

Steps


The `templates/examples/` directory in this repo contains ready-to-use templates you can copy into your vault:

- `JOURNAL.md` — Daily journal with date auto-filled (`agent_access: "append"`)
- `RECIPE.md` — Recipe with source and ingredients
- `MEETING_NOTES.md` — Meeting notes with attendees array (`agent_access: "edit"`)
- `REFERENCE_DOC.md` — Reference document with dynamic `agent_access` via `{{AGENT_ACCESS}}`

### Agent access in templates

Templates can include an `agent_access` frontmatter field to declare how freely an agent should edit the note after creation.

**Hardcoded in template** (e.g. JOURNAL.md always appends):```markdown
---
date: '{{TODAY}}'
agent_access: 'append'
---

Dynamic via placeholder (e.g. REFERENCE_DOC.md — set at creation time):```markdown

title: '{{TITLE}}'
agent_access: '{{AGENT_ACCESS}}'



When using the dynamic placeholder, pass `agent_access` to `create_note_from_template` and the value is inferred from the user's phrasing:

| User says…                                               | Inferred value |
| -------------------------------------------------------- | -------------- |
| "you can edit/update/modify" or "fully editable"         | `edit`         |
| "you can add to" or "append-only"                        | `append`       |
| No specific instruction                                  | `append`       |
| "read-only", "I'll edit this myself", "just create it"   | `read`         |
| "this is private", "keep this hidden", "don't show this" | `hidden`       |

If `agent_access` is passed explicitly to `create_note_from_template`, it overrides whatever value the template has (hardcoded or placeholder).

### Template placeholders

The following `{{PLACEHOLDER}}` tokens are automatically replaced when a note is created:

| Placeholder        | Example output                                                              |
| ------------------ | --------------------------------------------------------------------------- |
| `{{TODAY}}`        | `2026-03-24`                                                                |
| `{{DATE}}`         | `2026-03-24` (alias for TODAY)                                              |
| `{{NOW}}`          | `2026-03-24 15:30:45`                                                       |
| `{{TIME}}`         | `15:30:45`                                                                  |
| `{{TIMESTAMP}}`    | `1742820645` (Unix timestamp)                                               |
| `{{YEAR}}`         | `2026`                                                                      |
| `{{MONTH}}`        | `03`                                                                        |
| `{{DAY}}`          | `24`                                                                        |
| `{{AGENT_ACCESS}}` | `"append"` (resolved from the `agent_access` parameter, default `"append"`) |

Placeholders are expanded after `field_values` are applied, so caller-supplied values always take precedence.

### Array fields

If a `field_values` value for an array-typed frontmatter field contains `and`, it's automatically split into a list:```
"William Gibson and Bruce Sterling" → ["William Gibson", "Bruce Sterling"]

Testing

Run the end-to-end test harness (requires a real vault):```bash
python test_server.py --vault /path/to/your/vault


Options:

- `--vault` — path to vault (overrides `VAULT_PATH` env)
- `--note` — specific note path to test `get_note` with
- `--query` — search term for `search_notes` (default: `"the"`)

Run the robustness suite, which builds a throwaway vault full of empty and
malformed notes and asserts that no single bad file breaks vault-wide
operations (no real vault needed):```bash
python test_vault_robustness.py

Troubleshooting

VAULT_PATH environment variable is not set
Copy .env.example to .env and set the path, or pass VAULT_PATH in your MCP client config.

Templates directory not found in vault
Create a templates/ folder in your vault root, or copy templates from templates/examples/ in this repo.

Insufficient permissions
The note has agent_access: read or hidden. Add agent_access: append or agent_access: edit to its frontmatter.

A note is missing from list_notes or search_notes
A note whose YAML frontmatter can't be parsed is skipped rather than exposed,
so one bad file never breaks results for the rest of the vault. The response
names it in a warnings array (and the server logs it to
stderr) — fix the --- block at the top of that file and it reappears.
get_note on the same file returns an explicit error naming the problem.
If a note is missing with no warning, check whether it's agent_access: hidden.

Empty (0-byte) .md files
Handled normally — treated as a note with no frontmatter and no content, which
means the default agent_access: append. They appear in list_notes and
list_writable_notes, never match a search, and don't affect other notes.

Frontmatter with a non-string agent_access
Values like agent_access: [append] or agent_access: true resolve to an
unknown level: the note stays visible but is not writable. Quote the value or
use one of hidden / read / append / edit.

Changes to server code aren't taking effect
Your MCP client keeps the server process alive. Restart the client (e.g. quit and relaunch Claude Desktop) to pick up code changes.

field_values not updating frontmatter
Check that the key names exactly match the YAML frontmatter keys in the template (case-sensitive). Use fields_applied in the response to confirm what was actually written.


Running the server manually```bash

python -m markdown_vault_mcp.server

or

markdown-vault-mcp
```

The server communicates over stdio and is normally launched automatically by your MCP client.


Migrating from obsidian-mcp v2

See MIGRATION.md for upgrade steps.


License

GNU Affero General Public License v3.0 — see LICENSE for the full text.

You are free to use, modify, and distribute this software under the AGPL v3 terms. If you run a modified version as a network service, you must make the modified source available to users of that service.


Feedback

This project is a work in progress, and may have bugs. You can submit a Github Issue if you encounter any problems, and I will probably fix it! Because I don't want to have that problem, either.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Obsidian MCP 81c3fb07 怎么安装?

在客户端按下面的安装命令接入:python -m venv .venv。装完在客户端配置里引用同一个包或端点。

Obsidian MCP 81c3fb07 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Obsidian MCP 81c3fb07 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Obsidian MCP 81c3fb07 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Obsidian MCP 81c3fb07 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Obsidian MCP 81c3fb07 能提供哪些能力?

资料显示约 10 个工具;能力标签包括 笔记系统、Python、Claude。具体工具清单以官方文档为准。

Obsidian MCP 81c3fb07 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Obsidian MCP 81c3fb07 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。