obsidian-mcp-server는 Obsidian Vault의 Markdown 문서를 AI 에이전트가 조회하고, 관련 근거를 선별하고, 컨텍스트로 압축해 활용할 수 있게 해주는 로컬 우선 MCP 서버입니다.
이 프로젝트에서 RAG는 특정 벡터 DB나 검색 엔진 선택을 뜻하지 않습니다. RAG는 Vault에서 후보 문서를 찾고, Agent 작업에 맞는 근거를 고르고, 컨텍스트 윈도우에 맞게 압축해 제공하는 Agent Context Pipeline입니다.
로컬 우선 동작: 외부 서비스나 별도로 운영해야 하는 검색 엔진 없이 사용자 머신에서 Vault 검색과 컨텍스트 준비를 수행합니다.
컨텍스트 선별: 키워드 검색과 시맨틱 검색을 결합해 Agent에게 제공할 근거 후보를 찾습니다.
명시적 RAG 통합: 모든 프롬프트에 백그라운드 검색을 붙이지 않고, Vault 관련 명령이나 도구 참조가 있을 때 문맥 수집 경로를 엽니다.
토큰 절약: 원문 전체를 밀어넣기보다 excerpt, evidence snippet, memory_packet 형태로 압축합니다.
로컬 모델 기반 검색: @huggingface/transformers, LanceDB, local reranker를 사용해 semantic retrieval을 로컬에서 수행합니다.
Elasticsearch 같은 검색 엔진도 retrieval backend로 사용할 수 있는 대안입니다. 다만 이 프로젝트의 기본 목표는 외부 서비스나 별도 검색 엔진에 의존하지 않는 로컬 단독 작업이므로, embedded retrieval stack을 기본값으로 선택합니다.
Related MCP server: Obsidian MCP
vault
search: 키워드와 의미 기반 검색을 결합한 하이브리드 후보 탐색
read: 특정 노트 본문과 메타데이터 조회
list_all: Vault 문서 목록 조회
stats: Vault 및 인덱스 상태 조회
collect_context: 주제와 연관된 문서를 선별해 memory_packet 생성
load_memory: 저장된 컨텍스트 메모리 스냅샷 로드
generate_property: 문서 내용을 바탕으로 frontmatter 후보 생성
write_property: frontmatter 쓰기
create_document_with_properties: 문서 분석 후 속성 생성/쓰기 2단계 워크플로우
organize_attachments: 문서 내 첨부파일 정리 및 링크 갱신
현재 기본 retrieval backend는 다음 순서로 동작합니다.
Keyword Search: 내부 Indexer로 정확한 단어 매칭 후보를 찾습니다.
Vector Search: LanceDB와 로컬 embedding model로 의미적으로 유사한 청크를 찾습니다.
RRF Fusion: 키워드 결과와 벡터 결과의 순위를 결합합니다.
Local Reranking: 상위 후보를 reranker로 다시 평가합니다.
Compression: 필요한 excerpt, source ref, memory packet만 Agent context로 제공합니다.
로컬 embedding/reranking 모델이 설치되지 않은 경우 서버는 키워드 검색으로 폴백합니다.
Node.js 22 이상
접근 가능한 Obsidian Vault 절대 경로
npx @sunub/obsidian-mcp-server setup이 명령은 로컬 semantic search와 reranking에 필요한 모델을 캐시에 설치합니다.
이미 패키지를 설치한 환경에서는 다음처럼 실행할 수도 있습니다.
obsidian-mcp-server setup모델 설치가 없으면 기본 키워드 검색은 동작하지만, semantic search와 reranking 품질은 사용할 수 없습니다.
Claude Desktop, Cursor, Copilot 등 MCP 클라이언트에는 다음처럼 등록합니다.
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@sunub/obsidian-mcp-server@latest"],
"env": {
"VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
}
}
}
}VAULT_DIR_PATH는 반드시 본인의 Vault 절대 경로로 바꿔야 합니다.
환경변수 | 기본값 | 용도 | 필수 |
| 없음 | Obsidian Vault 절대 경로 | 예 |
|
|
| 아니오 |
|
| CLI UI가 사용할 OpenAI 호환 로컬 LLM endpoint | CLI 사용 시 |
|
| CLI UI 답변 생성 모델명 | CLI 사용 시 |
MCP 서버의 Vault 검색/읽기 도구에는 VAULT_DIR_PATH가 핵심 설정입니다. LLM_API_URL과 LLM_CHAT_MODEL은 저장소에 포함된 개발용 CLI UI에서 대화형 스트리밍 답변을 받을 때 필요합니다.
이 저장소에는 터미널 기반 AI Agent UI가 포함되어 있습니다. 이 CLI는 npm 패키지의 공개 bin이 아니라 저장소 개발 환경에서 실행하는 진입점입니다.
이 CLI의 목적은 Obsidian Vault를 단순히 검색하는 수준을 넘어서, MCP 도구 호출, 조건부 RAG 기반 문맥 수집, OpenAI 호환 LLM endpoint 스트리밍 응답을 하나의 대화형 작업 흐름으로 묶는 데 있습니다. 즉, 단순한 "채팅 UI"만 구현하는 곳이 아니라, Vault와 도구, 모델 사이를 연결하는 오케스트레이션 레이어입니다.
프로젝트의 문서와 설계 방향을 기준으로 보면, 이 CLI는 다음 문제를 해결하거나 완화하기 위해 만들어졌습니다.
외부 AI 서비스 의존성 감소: 프로젝트가 로컬 Vault와 로컬 도구를 다루는 만큼, 가능한 한 로컬 실행 환경에서 독립적으로 동작하도록 지향합니다.
문맥 손실 감소: Vault 관련 도구가 트리거된 질문에서는 관련 문서를 수집하고 요약해 LLM에 함께 전달할 수 있습니다.
토큰 낭비 감소: collect_context 기반 압축 요약과 대량 입력 오프로딩을 통해 긴 문서나 대형 paste를 그대로 모델에 밀어넣지 않습니다.
터미널 입력 안정성 개선: Raw mode 기반 입력 환경에서 발생하는 paste storm, 다중 Enter 트리거, 버퍼 오염 같은 문제를 제어합니다.
장시간 세션 안정성 확보: 스트리밍 취소, 히스토리 pruning, scrollback 위임 같은 구조를 통해 메모리 사용량과 렌더링 부담을 줄입니다.
사용자는 터미널에서 자연어로 질문을 입력하고, CLI는 LLM 서버와 통신해 답변을 스트리밍합니다.
응답을 실시간으로 출력합니다.
모델의 thinking 영역이 있으면 중간 추론 상태도 별도로 렌더링합니다.
완료된 대화는 히스토리에 반영하고, 진행 중 응답은 별도 pending 상태로 관리합니다.
CLI는 MCP 서버에 연결된 도구를 터미널에서 직접 사용할 수 있게 합니다.
/search, /read, /stats, /context, /tools 같은 슬래시 커맨드를 제공합니다.
사용자의 명시적 명령뿐 아니라, LLM이 tool call을 생성했을 때도 이를 실행할 수 있는 루프를 제공합니다.
여러 MCP 서버에 연결하고, 각 서버의 도구 목록과 연결 상태를 함께 관리합니다.
이 CLI는 모든 일반 질문에 대해 자동으로 RAG를 수행하지는 않습니다. 현재 구현 기준으로는 입력 텍스트에서 vault 도구나 관련 서버/도구 이름이 트리거된 경우에만 Vault 문맥 수집을 시도하고, 이를 <context> 블록으로 정리해 프롬프트에 주입합니다.
collect_context 액션을 활용해 관련 문서를 배치 단위로 수집합니다.
memory_packet과 고연관 문서 excerpt를 조합해 LLM 입력을 구성합니다.
따라서 이 CLI는 항상 RAG가 붙는 채팅창이라기보다, 필요 시 Vault-aware 동작을 수행하는 agent UI에 가깝습니다.
긴 코드, 로그, 문서가 붙여넣기되면 이를 그대로 모델에 보내는 대신 안전하게 축약/오프로딩합니다.
큰 paste는 임시 파일로 분리해 저장합니다.
LLM에는 전체 본문 대신 파일 위치와 미리보기, 처리 지시문을 전달합니다.
이 방식은 토큰 사용량을 줄이고, 필요할 때만 도구를 통해 원문을 읽게 만듭니다.
CLI UI는 응답이 끝난 뒤 한 번에 보여주는 구조가 아니라, 생성 중인 상태를 즉시 보여주는 흐름을 중심으로 설계되어 있습니다.
입력 직후 버퍼를 비워 다음 작업을 준비합니다.
첫 토큰 전에는 thinking/processing 상태를 보여줍니다.
완료된 기록은 정적 영역으로 넘기고, 현재 응답만 동적으로 다시 렌더링합니다.
사용자가 메시지 또는 슬래시 커맨드를 입력합니다.
질문 내용에서 Vault 관련 도구가 트리거되면 관련 문맥 수집을 시도합니다.
LLM 스트리밍 요청을 시작합니다.
필요 시 MCP 도구를 호출합니다.
응답을 실시간으로 출력합니다.
완료된 결과를 히스토리에 반영하고 다음 입력을 기다립니다.
영역 | 역할 | 대표 파일 |
부팅 및 환경 확인 | LLM endpoint 확인, 초기 로더/에러 화면 제어 |
|
MCP 연결 관리 | 설정 파일 기반 MCP 서버 연결, 도구 목록 수집, 멀티 서버 상태 관리 |
|
입력 시스템 | Raw key 처리, paste 버퍼링, 멀티라인 편집, 히스토리 탐색 |
|
명령 디스패치 | 슬래시 커맨드를 MCP 도구 호출로 변환 |
|
RAG 컨텍스트 수집 | Vault 관련 도구가 트리거된 질문에서만 문맥을 수집해 프롬프트에 주입 |
|
LLM 스트리밍 루프 | 스트리밍 응답, tool call 실행, thinking 파싱 |
|
렌더링 및 세션 관리 | 히스토리 출력, pending 응답 표시, transient UI 메시지 관리 |
|
대량 입력 최적화 | 큰 붙여넣기 입력 오프로딩 및 임시 파일 정리 |
|
이 CLI는 다음 원칙을 중심으로 설계됩니다.
입력과 렌더링의 분리
스트리밍 우선 UX
설정 파일 기반 MCP 연결
도구 호출과 대화 흐름의 통합
토큰/메모리 효율 최적화
중단 가능성과 복구 가능성 보장
현재 코드 기준으로 기본 제공되는 대표 슬래시 커맨드는 다음과 같습니다.
/search <keyword>: Vault 하이브리드 검색
/read "filename": 특정 문서 열람
/semantic <query>: 시맨틱 검색
/stats: Vault 상태 확인
/index: 벡터 인덱스 갱신
/context <topic>: 토픽 기반 문맥 수집
/organize <keyword>: 첨부 정리 도구 실행
/genprop <filename>: frontmatter 생성 도구 호출
/tools: 연결된 MCP 도구 목록 확인
/help: 도움말 표시
/clear: 화면/대화 상태 초기화
/quit, /exit: CLI 종료
현재 CLI 진입점은 저장소 개발 환경용 실행 방식입니다. 패키지의 bin 엔트리는 MCP 서버용이며, CLI UI는 루트에서 별도 스크립트로 실행됩니다.
저장소 루트에서 의존성을 설치하고 서버를 먼저 빌드합니다.
npm install
npm run build이 저장소 루트에는 기본 mcp-servers.json이 포함되어 있으며, node ./build/index.js로 서버를 실행합니다.
그 다음 OpenAI 호환 로컬 LLM 서버를 실행합니다. 예를 들어 llama.cpp의 llama-server를 8080 포트에 띄울 수 있습니다.
llama-server -m /path/to/model.gguf --port 8080CLI는 다음처럼 환경 변수를 주입하여 실행합니다:
VAULT_DIR_PATH="/Users/username/Documents/MyVault" \
LLM_API_URL="http://127.0.0.1:8080" \
LLM_CHAT_MODEL="llama3" \
npm run cliCLI는 실행 시 현재 작업 디렉터리에서 다음 파일을 순서대로 찾습니다.
mcp-servers.json
.mcp-servers.json
설정 파일이 없으면 환경 변수 기반 fallback을 시도하지만, 가장 안전한 실행 방식은 저장소 루트에서, build/index.js가 준비된 상태로 실행하는 것입니다.
이 CLI 실행 방법은 개발용 CLI UI 진입점 기준입니다. 배포된 npx @sunub/obsidian-mcp-server는 MCP 서버를 띄울 뿐 CLI UI를 실행하지 않습니다.
CLI가 MCP 서버에 연결되려면 현재 디렉터리의 mcp-servers.json 또는 .mcp-servers.json이 유효해야 합니다.
VAULT_DIR_PATH가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.
semantic search와 reranking을 쓰려면 서버 setup으로 로컬 모델을 설치해야 합니다.
VAULT_DIR_PATH가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.
semantic search와 reranking을 쓰려면 setup으로 로컬 모델을 설치해야 합니다.
CLI UI를 쓰려면 별도의 OpenAI 호환 로컬 LLM 서버가 실행 중이어야 합니다.
CLI의 명시적 RAG는 vault 관련 명령, 서버명, 도구명이 입력에서 트리거될 때만 사전 문맥 수집을 시도합니다.
collect_context는 긴 주제 정리와 메모리 패킷 생성에 적합하고, 단건 조회는 search나 read가 더 단순합니다.
쓰기 계열 도구는 Vault 바깥 경로에 쓰지 않도록 차단합니다.
Apache-2.0
Starts and completes a two-step workflow for AI-generated frontmatter properties.
Step 1: Call this tool with sourcePath (and optional outputPath). It returns a structured instruction payload and a content preview for AI analysis. Step 2: Call this same tool again with aiGeneratedProperties. The tool then writes those properties by executing the same write logic used by the 'write_property' tool.
Use this tool when an AI agent should orchestrate analysis and write in a consistent workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| quiet | No | If true, the final write operation will return a minimal success message. | |
| overwrite | No | If set to true, existing properties will be overwritten by the AI-generated content. Default: false. | |
| outputPath | No | The path where the processed file with properties will be saved. If not provided, the source file will be updated in place. | |
| sourcePath | Yes | The path to the source markdown file to read and analyze (e.g., "draft/my-article.md") | |
| aiGeneratedProperties | No | AI-generated properties based on content analysis. If provided, these will be used instead of internal analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include openWorldHint: true, indicating side effects. The description details the two-step workflow, including that it writes properties using the same logic as write_property. It adds context beyond annotations by explaining the workflow and return of structured payload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first sentence states purpose, then numbered steps, then usage guidance. No wasted words, each sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (5 params, nested objects, workflow). The description covers the workflow and parameter roles adequately. No output schema, but it mentions the return format implicitly. Slightly incomplete on return specifics but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline 3. The description adds value by explaining parameter roles in the workflow, such as sourcePath for reading and aiGeneratedProperties for the second call, going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: starting and completing a two-step workflow for AI-generated frontmatter properties. It clearly distinguishes from sibling tools like write_property and generate_property by describing a compound workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises when to use the tool: when an AI agent should orchestrate analysis and write in a consistent workflow. It implies but does not explicitly state when not to use it or mention alternatives, though it references the same write logic as write_property.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads a target markdown document and returns an AI-facing payload for generating frontmatter properties.
This tool does not write to disk. It returns content_preview and a target output schema so an AI can produce a valid property object.
Use Cases:
After completing a draft, when you need property suggestions from content.
When missing frontmatter fields (title, tags, summary, slug, date, category, completed) should be generated.
To apply generated properties to a file, call 'write_property' with the resulting JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | The name or path of the file to analyze and add properties to (e.g., "my-first-post.md") | |
| overwrite | No | If set to true, existing properties will be overwritten by the AI-generated content. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (only openWorldHint=true), but the description compensates by explicitly stating 'This tool does not write to disk' and describing the return payload (content_preview and target output schema). This provides sufficient behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs with bullet points for use cases. It is concise and front-loaded with the core function. The extra sentences about use cases and linking to write_property earn their place, though the overwrite default contradiction adds unnecessary confusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return structure adequately. It covers use cases and references to sibling tools. However, it fails to mention the potential side effect of overwrite when combined with write_property, and the default value inconsistency hurts completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description contains a contradiction: it states 'Default: false' for the 'overwrite' parameter, but the input schema shows 'default': true. This inconsistency could mislead the agent. The description does add the context of overwriting existing properties, but the error reduces reliability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reads a target markdown document and returns an AI-facing payload for generating frontmatter properties.' The verb 'reads' and resource 'markdown document' are specific, and the distinction from the sibling 'write_property' is clear because it explicitly says this tool does not write to disk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'After completing a draft, when you need property suggestions from content' and 'When missing frontmatter fields should be generated.' It also advises to use 'write_property' to apply the generated properties. However, it does not compare against all siblings like 'create_document_with_properties', which might have overlapping functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scans a specified markdown file for linked images (or other attachments), moves them to a dedicated folder named after the document's title, and updates the links within the markdown file automatically.
Use Cases:
When a post is finalized and you want to clean up all associated images into a neat folder.
To automatically organize attachments for better vault management.
Example Workflow:
Specify 'my-awesome-post.md' as the fileName.
The tool finds the 'title' property in the frontmatter (e.g., "My Awesome Post").
It finds all image links like ![[my-image.png]].
It creates a folder at '{vault}/images/My Awesome Post/'.
It moves 'my-image.png' into that new folder.
It updates the link in the markdown file to ![[images/My Awesome Post/my-image.png]].
| Name | Required | Description | Default |
|---|---|---|---|
| quiet | No | If true, returns a minimal success message. | |
| keyword | Yes | A keyword to search for the markdown file within the vault. | |
| destination | No | The base folder to move attachments into. Defaults to "images". | images |
| useTitleAsFolderName | No | If true, creates a subfolder named after the document title. Defaults to true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description openly describes the tool's actions: scanning a file, moving attachments to a new folder, and updating links. This discloses its mutating behavior, aligning with the openWorldHint annotation. It doesn't elaborate on reversibility or permissions, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with a clear action, followed by use cases and an example workflow. Every sentence adds meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema), the description covers the process thoroughly, including the steps and file organization. It does not explain return values or error handling, but this is acceptable since there is no output schema. The example workflow compensates for minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the input schema, and the description adds value through an example workflow that illustrates how keyword, destination, and useTitleAsFolderName are used. The quiet parameter is not elaborated in the description beyond the schema, so the description adds limited additional semantics beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scans a markdown file for attachments, moves them to a dedicated folder, and updates links. It includes specific use cases and an example workflow, making the purpose unmistakable and distinct from sibling tools like create_document_with_properties or vault.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases, such as when a post is finalized and you want to clean up attachments. However, it does not explicitly state when not to use the tool or mention alternatives, though the sibling tools are sufficiently different to avoid confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves and searches the content of Markdown (.md, .mdx) documents stored in an Obsidian vault. Use this tool to find notes related to a specific topic or keyword and understand their core content.
When to use:
When you need to find a specific note by its title or a keyword to check its content.
When you want to synthesize and summarize information scattered across multiple notes.
When looking for answers to questions based on your saved records, such as "What was the project deadline?"
To discover connections by finding all notes that link to a specific note.
When you need to retrieve a list of unfinished tasks (- [ ]) from daily notes or meeting minutes.
Use "index_vault_to_vectordb" to manually trigger a full re-indexing of the vault for the vector database.
Returns the content of the most relevant document(s) in text format. It can also include metadata such as the document's title, tags, and creation date.
Requirements: The user's Obsidian Vault path must be correctly configured in an environment variable or a similar setting. For searches, use the exact filename or include core keywords for content-based queries.
IMPORTANT INSTRUCTION FOR AI: If the tool response includes a 'diagnostic_message' (usually found at the beginning of the text or in a tag), you MUST relay this information to the user exactly once. It contains essential advice on how to improve search quality by running a local setup script via 'npx @sunub/obsidian-mcp-server setup'. Do not ignore it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default: 10 for search, unlimited for others) | |
| query | No | Natural language query for filtering content paragraphs using the local reranker (optional for read action) | |
| quiet | No | If true, suppresses non-error output messages. Default is false. | |
| scope | No | Scope for collect_context. topic: collect docs relevant to topic, all: collect from the entire vault. | topic |
| topic | No | Topic to collect contextual memory for (collect_context action) | |
| action | Yes | The action to perform: search documents, read specific file, list all content, get stats, collect contextual memory packets, load stored memory, or trigger indexing | |
| keyword | No | Keyword to search for in documents (required for search action) | |
| maxDocs | No | Maximum number of documents to process for collect_context | |
| filename | No | Specific filename to read (required for read action) | |
| memoryMode | No | Memory output mode for collect_context. response_only: return packet only, vault_note: save to vault note only, both: return and save. | response_only |
| memoryPath | No | Path to a stored memory note for load_memory (default: memory/context_memory_snapshot.v1.md) | |
| excerptLength | No | Length of content excerpt to include in search results (default: 500) | |
| includeContent | No | Whether to include document content in search results (default: true) | |
| maxCharsPerDoc | No | Maximum number of characters extracted per document for collect_context | |
| maxOutputChars | No | Optional hard cap for output size in characters. Helps control token cost in long responses. | |
| compressionMode | No | Compression strategy for tool output. summary: lightest TOC & document summary only (default), aggressive: smallest output, balanced: moderate size, none: keep as much original content as possible. | summary |
| continuationToken | No | Continuation token to resume a previous collect_context batch operation | |
| includeFrontmatter | No | Whether to include frontmatter metadata in results (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide openWorldHint. The description adds behavioral details: returns content and metadata, and includes crucial instruction about relaying diagnostic messages. This goes beyond annotations by disclosing expected output and a user interaction requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, when to use, return info, requirements, important instruction). It is front-loaded with the primary purpose. Though slightly verbose, every section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (18 parameters, enums, no output schema), the description covers usage scenarios, return format, requirements, and a critical instruction. It provides sufficient context for an AI agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are described in the schema. The description adds contextual usage hints (e.g., 'use exact filename or core keywords for searches'), which enhances understanding beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves and searches Markdown documents in an Obsidian vault, specifying verb (retrieves, searches) and resource (Markdown documents). It implicitly distinguishes from sibling tools (which are for writing/properties) by focusing on reading/searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a detailed 'When to use' section with specific scenarios (find note, synthesize info, find answers, etc.) and mentions triggering re-indexing. However, it does not explicitly state when not to use the tool or compare with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Description: Adds or updates properties within the frontmatter section at the top of a specified Obsidian markdown file. This tool is primarily used to apply metadata generated by the 'generate_property' tool to an actual file.
Parameters:
filePath (string, required): The path to the target markdown file to which properties will be added or updated. Example: "my-first-post.md"
properties (object, required): A JSON object containing the key-value pairs to be written to the file's frontmatter. If a property with the same key already exists in the file, it will be overwritten with the new value.
Example:
JSON { "title": "Optimizing I/O Handling in a Serverless Environment", "date": "2025-04-03", "tags": ["serverless", "optimization"], "summary": "A case study on optimizing I/O in a serverless environment by benchmarking Promise.all and Workers.", "completed": true }
Return Value:
Upon successful execution, it returns a JSON object containing the status, a confirmation message, and the property object that was applied to the file.
Example:
JSON { "status": "success", "message": "Successfully updated properties for my-first-post.md", "properties": { "title": "Optimizing I/O Handling in a Serverless Environment", "date": "2025-04-03", "tags": ["serverless", "optimization"], "summary": "A case study on optimizing I/O in a serverless environment by benchmarking Promise.all and Workers.", "completed": true } }
Dependencies & Requirements:
Input Data: The properties parameter should typically be the JSON object output from the 'generate_property' tool.
Environment Setup: The absolute path to the user's Obsidian Vault must be correctly set as an environment variable.
| Name | Required | Description | Default |
|---|---|---|---|
| quiet | No | If true, suppresses non-error output messages. Default is false. | |
| filePath | Yes | Path to the target markdown file within the Obsidian vault | |
| properties | Yes | Key-value pairs to be written to the file's frontmatter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains overwrite behavior for existing properties and provides return value format. With only openWorldHint annotation, it adds meaningful transparency beyond what annotations offer. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for overview, parameters, return value, and dependencies. Examples are helpful but slightly verbose. Front-loaded with purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage, dependencies, and return value. No output schema, but description provides example. Could explicitly differentiate from siblings like 'create_document_with_properties', but overall sufficiently complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value with examples and overwrite behavior for the properties object, but omits the 'quiet' parameter entirely, and schema default (true) contradicts description's implied default (false) if quiet were mentioned. This reduces score slightly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds/updates properties in Obsidian frontmatter, explicitly linking it to the 'generate_property' tool for applying metadata. It distinguishes from siblings like 'create_document_with_properties' by focusing on existing files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates primary use case (apply metadata from generate_property) and prerequisites (vault path environment variable). It lacks explicit when-not-to-use instructions but provides sufficient context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.30vault3 fields changedInput schema / properties / compressionMode / defaultPrevious value: -"balanced"New value: +"summary"Input schema / properties / compressionMode / descriptionPrevious value: -"Compression strategy for tool output. aggressive: smallest output, balanced: default, none: keep as much original content as possible."New value: +"Compression strategy for tool output. summary: lightest TOC & document summary only (default), aggressive: smallest output, balanced: moderate size, none: keep as much original content as possible."Input schema / properties / compressionMode / enumPrevious value: -[
- "aggressive",
- "balanced",
- "none"
-]New value: +[
+ "summary",
+ "aggressive",
+ "balanced",
+ "none"
+]v0.3.29vault3 fields changedInput schema / properties / action / descriptionPrevious value: -"The action to perform: search documents, read specific file, list all content, get stats, collect contextual memory packets, load stored memory, semantic search, or trigger indexing"New value: +"The action to perform: search documents, read specific file, list all content, get stats, collect contextual memory packets, load stored memory, or trigger indexing"Input schema / properties / action / enumPrevious value: -[
- "search",
- "read",
- "list_all",
- "stats",
- "collect_context",
- "load_memory",
- "search_vault_by_semantic",
- "index_vault_to_vectordb"
-]New value: +[
+ "search",
+ "read",
+ "list_all",
+ "stats",
+ "collect_context",
+ "load_memory",
+ "index_vault_to_vectordb"
+]Input schema / properties / query / descriptionPrevious value: -"Natural language query for semantic search (required for search_vault_by_semantic action)"New value: +"Natural language query for filtering content paragraphs using the local reranker (optional for read action)"v0.3.20vault12 fields changedInput schema / properties / action / descriptionPrevious value: -"The action to perform: search documents, read specific file, list all content, or get stats"New value: +"The action to perform: search documents, read specific file, list all content, get stats, collect contextual memory packets, load stored memory, semantic search, or trigger indexing"Input schema / properties / action / enumPrevious value: -[
- "search",
- "read",
- "list_all",
- "stats"
-]New value: +[
+ "search",
+ "read",
+ "list_all",
+ "stats",
+ "collect_context",
+ "load_memory",
+ "search_vault_by_semantic",
+ "index_vault_to_vectordb"
+]Input schema / properties / compressionModeAdded value: +{
+ "default": "balanced",
+ "description": "Compression strategy for tool output. aggressive: smallest output, balanced: default, none: keep as much original content as possible.",
+ "enum": [
+ "aggressive",
+ "balanced",
+ "none"
+ ],
+ "type": "string"
+}Input schema / properties / continuationTokenAdded value: +{
+ "description": "Continuation token to resume a previous collect_context batch operation",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / maxCharsPerDocAdded value: +{
+ "default": 1800,
+ "description": "Maximum number of characters extracted per document for collect_context",
+ "maximum": 8000,
+ "minimum": 200,
+ "type": "integer"
+}Input schema / properties / maxDocsAdded value: +{
+ "default": 20,
+ "description": "Maximum number of documents to process for collect_context",
+ "maximum": 100,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / maxOutputCharsAdded value: +{
+ "description": "Optional hard cap for output size in characters. Helps control token cost in long responses.",
+ "maximum": 12000,
+ "minimum": 500,
+ "type": "number"
+}Input schema / properties / memoryModeAdded value: +{
+ "default": "response_only",
+ "description": "Memory output mode for collect_context. response_only: return packet only, vault_note: save to vault note only, both: return and save.",
+ "enum": [
+ "response_only",
+ "vault_note",
+ "both"
+ ],
+ "type": "string"
+}Input schema / properties / memoryPathAdded value: +{
+ "description": "Path to a stored memory note for load_memory (default: memory/context_memory_snapshot.v1.md)",
+ "type": "string"
+}Input schema / properties / queryAdded value: +{
+ "description": "Natural language query for semantic search (required for search_vault_by_semantic action)",
+ "type": "string"
+}Input schema / properties / scopeAdded value: +{
+ "default": "topic",
+ "description": "Scope for collect_context. topic: collect docs relevant to topic, all: collect from the entire vault.",
+ "enum": [
+ "topic",
+ "all"
+ ],
+ "type": "string"
+}Input schema / properties / topicAdded value: +{
+ "description": "Topic to collect contextual memory for (collect_context action)",
+ "minLength": 1,
+ "type": "string"
+}create_document_with_propertiesgenerate_propertyorganize_attachmentsvaultwrite_propertyEach tool has a clearly distinct purpose: vault for searching/reading, generate_property for reading and suggesting properties, write_property for writing properties, create_document_with_properties for a two-step workflow, and organize_attachments for file management. No significant overlap.
Most tools follow a verb_noun pattern (generate_property, write_property, organize_attachments), but create_document_with_properties is a longer phrase and vault is a single noun without a verb, breaking consistency.
5 tools is well-scoped for an Obsidian vault management server, covering essential operations without being too few or too many.
Core workflows (reading, property generation/application, attachment organization) are covered. Minor gaps like lacking a delete property or blank document creation are acceptable given the server's focus.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sunub/obsidian-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
