Obsidian MCP Server Claude Code: 5 Lựa Chọn Thực Tế 2026

Obsidian MCP server Claude Code kết nối Obsidian vault với Claude Code qua Model Context Protocol, cho phép AI agent đọc/ghi vault qua chuẩn protocol thay vì filesystem direct. PulseMCP hiện liệt kê 66 Obsidian MCP servers (tăng từ ~24 trong đầu 2026), nhưng chỉ khoảng 8 server có meaningful traction. Bài này so sánh 5 implementation thực tế cho developer: iansinnott obsidian-claude-code-mcp (303 stars), mcp-obsidian, obsidian-mcp, MCPVault, jacksteamdev obsidian-mcp-tools.

Pillar Obsidian + Claude Code đã giới thiệu briefly 5 cách kết nối, trong đó MCP plugin là Cách 3. Bài này đào sâu MCP architecture, compare 5 server, setup chi tiết cho từng option, và pattern phù hợp với use case khác nhau. Mình đã thử 3 trong 5 server, kết quả đo cụ thể ở section cuối.

Obsidian MCP Server Là Gì?

Obsidian MCP server là service implement Model Context Protocol để kết nối Obsidian vault với AI agent (Claude Code, Claude Desktop, Cursor, Gemini CLI). MCP cung cấp standardized way để LLM agent gọi tools đọc/ghi vault, không phải hard-code filesystem path. Cho developer, MCP layer này quan trọng khi muốn dùng nhiều agent khác nhau truy cập cùng một vault.

Khác với approach filesystem direct (Claude Code chỉ cần cd ~/vault && claude), MCP server thêm abstraction layer. Lợi: agent không thấy file system thật, chỉ thấy tools (view, create, edit). Plugin có thể implement business logic (validation, conflict detection) trước khi commit thay đổi. Nhược: setup phức tạp hơn, port conflict, version mismatch giữa MCP spec versions.

Pillar Obsidian + Claude Code Cách 3 đã introduce MCP plugin. 3-layer architecture explain CLAUDE.md schema layer hoạt động ra sao. CLAUDE.md 5 templates cung cấp template per project type. Bài này focus về MCP transport layer cụ thể.

2 Architecture: REST API vs Filesystem Khác Nhau Như Thế Nào?

Obsidian MCP servers chia thành 2 architecture camps theo cách access vault. REST API servers cần plugin Obsidian Local REST API + Obsidian phải đang chạy. Filesystem servers đọc/ghi markdown trực tiếp trên disk, không cần Obsidian mở.

REST API approach. Server gọi HTTP endpoint Obsidian expose qua plugin Local REST API. Mọi file operation đi qua Obsidian, không bypass app logic. Lợi: file lock conflict được Obsidian handle, plugin Obsidian khác (Templater, Dataview) work bình thường, validation rule (max file size, naming) áp dụng đầy đủ. Nhược: Obsidian phải đang chạy, cần plugin + API key, performance overhead vì HTTP layer. Implementations: mcp-obsidian (MarkusPfundstein), obsidian-mcp-server (marcelmarais).

Filesystem approach. Server đọc/ghi markdown direct trên file system, không thông qua Obsidian. Lợi: standalone, Obsidian không cần mở, faster cho bulk operation, simpler setup (npx obsidian-mcp /path/to/vault đủ). Nhược: bypass Obsidian validation, có thể conflict nếu Obsidian cũng đang edit cùng file, plugin behavior không mirror. Implementations: obsidian-mcp, MCPVault, iansinnott obsidian-claude-code-mcp.

Quyết định architecture nào tùy use case. Heavy plugin user (Templater, Dataview, sync conflict prevention) → REST API. Casual user, multi-vault, automation script → Filesystem. Trong 3 vault mình đang dùng, 2 vault personal + research dùng filesystem (đơn giản), 1 vault team dùng REST API (cần Templater conflict prevention).

iansinnott obsidian-claude-code-mcp Có Gì Đặc Biệt Với 7 Tools?

Plugin obsidian-claude-code-mcp của Ian Sinnott (303 stars (tính đến 14/6/2026), latest 1.1.8 từ tháng 6/2025) là MCP plugin phổ biến nhất trong ecosystem Obsidian. Filesystem-based với dual transport: WebSocket cho Claude Code, HTTP/SSE cho Claude Desktop, cùng port 22360 mặc định.

7 tools cốt lõi:

Tool get_current_file đặc biệt useful vì cho Claude biết bạn đang xem file nào trong Obsidian ngay lúc đó. Khi bạn ở wiki/concepts/llm-wiki.md và hỏi Claude “expand section này”, Claude tự biết file path mà không cần bạn paste. Đây là context awareness mà filesystem-only approach không có.

Setup. Cài plugin qua Obsidian Community Plugins, search “Claude Code”, Enable. Trong Claude Code chạy /ide → chọn Obsidian → kết nối tự động qua WebSocket. Nếu port 22360 conflict với app khác, edit plugin settings đổi port khác.

Limitation đáng lưu ý. Plugin dùng MCP spec 2024-11-05 (legacy) thay vì latest “Streamable HTTP” vì client support chưa đầy đủ. Multi-vault running cùng lúc cần manual port config. Một số IDE-specific tools (diff view, tab management) là stub không implement đầy đủ.

mcp-obsidian REST API Approach Phù Hợp Power User Khi Nào?

mcp-obsidian của MarkusPfundstein là REST API approach phổ biến nhất. Cần plugin Obsidian Local REST API cài trước, sau đó Python-based MCP server connect qua HTTP. Phù hợp developer heavy plugin user vì Obsidian mediate mọi operation.

8 tools available:

list_files_in_vault       # List toàn vault
list_files_in_dir         # List sub-folder cụ thể
get_file_contents         # Đọc file
search                    # Search vault content
patch_content             # Update file qua diff patch
append_content            # Append vào cuối file
delete_file               # Xóa file (cần confirm)

Setup phức tạp hơn iansinnott. Cần Local REST API plugin (config certificate + port + key), Python environment cho MCP server, sau đó claude_desktop_config.json hoặc Claude Code MCP config trỏ tới Python server. Tổng setup ~20 phút lần đầu.

Lợi thế. Validation tốt hơn: Templater post-create hooks chạy bình thường, Dataview index update real-time, sync conflict prevention từ Obsidian. Trade-off: performance overhead 100-300ms mỗi tool call so với filesystem direct.

Mình dùng mcp-obsidian cho team vault có 8 plugin active. Dùng được nhưng phức tạp setup mỗi máy team member. Khuyến cáo team trên 3 người: setup script automate config qua Ansible hoặc Make.

obsidian-mcp + MCPVault: Setup Đơn Giản Nhất

obsidian-mcp và MCPVault là 2 filesystem server đơn giản nhất, không cần plugin, không cần API key. Phù hợp dev mới start, multi-vault automation, hoặc scripts CI/CD.

obsidian-mcp setup:

# Một dòng, không cài plugin Obsidian
npx obsidian-mcp /path/to/vault

# Configure Claude Code MCP
claude mcp add obsidian \
  --command "npx obsidian-mcp /Users/me/Documents/MyVault"

12 tools: read-note, create-note, edit-note, delete-note, move-note, create-directory, search-vault, add-tags, remove-tags, rename-tag, manage-tags, list-available-vaults. Multi-vault support out of the box, list-available-vaults discover vaults trên máy tự động.

MCPVault tương tự nhưng minimal hơn:

npx @bitbonsai/mcpvault@latest /path/to/vault

Tools đơn giản: read, create, edit, search, list. Phù hợp use case đơn giản (auto-archive, batch rename, generate report). Performance fastest trong 5 options vì least abstraction.

Mình dùng MCPVault cho automation script chạy nightly: rebuild wiki/index.md, lint orphan pages, append weekly review template chuẩn bị thứ Hai. Script chạy 2 phút, không cần Obsidian mở. Setup đơn giản đến mức không cần document.

jacksteamdev obsidian-mcp-tools: Power Tools

obsidian-mcp-tools là approach khác: integrate semantic search và custom Templater prompts vào MCP. Heavy hơn 4 server trên, focus vào AI-native features hơn là raw file operations.

Features chính. Semantic search qua embedding model local (giúp query “tìm note related to X” mạnh hơn keyword search). Custom Templater prompts wrap thành MCP tools (bạn có custom workflow Templater, expose như MCP tool cho Claude trigger). Multi-vault index unified.

Trade-off. Setup phức tạp nhất trong 5 options (cần embedding model, Templater plugin, custom config). Performance overhead embedding compute. Phù hợp khi vault qua 1000 notes và keyword search không đủ. Ít người dùng hơn 4 option khác (community resources giới hạn).

Mình chưa dùng plugin này production. Test 1 tuần trên test vault, embedding quality tốt, response time chấp nhận được. Có thể migrate research vault sang khi vault grow qua 800 notes (hiện 300, chưa cần).

Cách Chọn MCP Server Phù Hợp Use Case

Decision tree đơn giản dựa trên 3 câu hỏi. Một, bạn có dùng Obsidian heavy plugin (Templater, Dataview)? Có → REST API approach (mcp-obsidian). Không → Filesystem approach. Hai, vault size hiện tại? Dưới 500 notes → obsidian-mcp hoặc MCPVault đơn giản. Qua 800 notes + cần semantic search → jacksteamdev obsidian-mcp-tools. Ba, dùng nhiều agent khác nhau (Claude Code + Cursor + Gemini)? Có → iansinnott (dual transport WebSocket + HTTP/SSE). Không → bất kỳ option nào.

Recommend cho developer theo experience level. Beginner (vault dưới 100 notes, dùng Claude Code only): bắt đầu KHÔNG cần MCP server. Filesystem direct (cd vault && claude) đã đủ. Setup MCP khi nào thật sự cần multi-agent. Intermediate (vault 100-500 notes, Claude Code chính): obsidian-mcp npx setup đơn giản. Advanced (vault qua 500 notes, multi-agent): iansinnott + jacksteamdev tùy use case.

MCP Server Kết Nối Claude Với Obsidian Vault Hoạt Động Ra Sao?

Phần này giải thích sâu hơn về cơ chế hoạt động của MCP server giúp Claude Code đọc và modify nội dung trong Obsidian vault. Hiểu rõ cơ chế bên trong giúp dev đưa ra quyết định config phù hợp với nhu cầu thực tế của dự án, tránh tình trạng setup sai gây mất thời gian xử lý sự cố về sau khi đã đầu tư công sức ban đầu vào phương án không phù hợp.

Trước khi đi vào chi tiết kỹ thuật của các MCP server cụ thể, người mới bắt đầu nên nắm vững khái niệm cốt lõi về MCP (Model Context Protocol) để hiểu nền tảng kiến trúc chung mà tất cả các MCP server đều dựa trên. MCP được thiết kế theo nguyên tắc tách biệt rõ ràng giữa Claude và data layer, mỗi bên có trách nhiệm riêng và giao tiếp qua các message có structure rõ ràng. Hiểu được nguyên lý này giúp team product dễ dàng mở rộng system về sau khi nhu cầu business thay đổi.

Tích hợp giữa MCP server và Obsidian đặc biệt phù hợp với pattern Karpathy LLM Wiki architecture đang được nhiều user tại VN áp dụng. Pattern này tổ chức knowledge base theo 3 layer riêng biệt, mỗi layer có vai trò khác nhau trong việc lưu trữ và retrieve thông tin. MCP server đóng vai trò cầu nối giữa Claude và cả 3 layer, cho phép query linh hoạt theo nhiều cách khác nhau mà không cần can thiệp thủ công. Đầu tư 2-3 ngày tìm hiểu kỹ pattern này trước khi triển khai MCP server giúp team product thiết kế system hợp lý ngay từ đầu, tránh việc phải refactor về sau khi đã có nhiều data trong vault.

Một yếu tố quan trọng khác cần xem xét khi config MCP server là khả năng sync vault giữa nhiều thiết bị khác nhau. Khi MCP server chạy trên desktop ở văn phòng nhưng user cũng access vault từ mobile hoặc laptop ở nhà, cần thiết lập cơ chế Obsidian Sync multi-device sao cho cả 3 thiết bị đều có cùng phiên bản data mới nhất. Pattern phổ biến nhất hiện nay là dùng Obsidian Sync chính thức hoặc self-hosted solution qua các open-source tool. Mỗi giải pháp có ưu nhược điểm riêng về chi phí, reliability, và mức độ data control, user nên đọc kỹ trước khi quyết định.

Lưu Ý Quan Trọng Khi Triển Khai MCP Server Cho Vault Lớn Là Gì?

Phần này tổng hợp 3 lưu ý quan trọng khi triển khai MCP server cho vault có quy mô lớn từ 500 note trở lên. Đây là các vấn đề thực tế mà nhiều team tại VN đã gặp phải trong 6 tháng đầu năm 2026 khi áp dụng pattern này vào production, đáng được chia sẻ cho người mới bắt đầu để tránh các sai lầm tốn kém về thời gian và công sức về sau.

Lưu ý đầu tiên là về performance khi vault có nhiều note và cross-link phức tạp. MCP server cần scan toàn bộ vault định kỳ để build search index, với vault lớn quá trình này có thể mất vài phút mỗi lần restart. Pattern khôn ngoan là setup incremental index thay vì build lại từ đầu mỗi lần, giảm startup time đáng kể từ vài phút xuống còn vài giây. Đặc biệt quan trọng khi team product cần restart server thường xuyên để apply các config mới mà không muốn chờ đợi lâu mỗi lần.

Lưu ý thứ hai là về cú pháp format trong các note có thể ảnh hưởng đến khả năng xử lý của MCP server. Một số MCP server chỉ hỗ trợ cú pháp markdown chuẩn của Obsidian, không hỗ trợ đầy đủ các extension đặc thù như wikilink có dấu cách hoặc attachment dạng đặc biệt. Team development nên check kỹ docs của MCP server trước khi triển khai để tránh tình trạng một số note không được xử lý đúng cách. Đầu tư 30 phút đọc kỹ docs hỗ trợ cú pháp giúp tiết kiệm hàng giờ khắc phục sự cố về sau khi phát hiện một số note quan trọng bị bỏ qua trong quá trình query.

Lưu ý thứ ba là về việc kết hợp với các community plugin phổ biến trong vault. Nếu vault đang dùng nhiều plugin để mở rộng chức năng, một số plugin có thể conflict với MCP server khi cùng access vault data đồng thời. Pattern bảo vệ tốt nhất là tham khảo plugin Obsidian must-have cho dev để chọn các plugin đã được kiểm chứng tương thích với MCP server. Trước khi cài plugin mới, hãy test trên môi trường staging trước, sau khi xác nhận không có conflict mới đưa vào production. Cách làm này tránh được tình trạng vault gặp sự cố không xác định nguồn gốc, khó debug khi có nhiều plugin chạy đồng thời.

Câu Hỏi Thường Gặp

MCP server có replace Claude Code filesystem direct không?

Không cần thay thế. MCP layer thêm khả năng (multi-agent access, validation hooks) nhưng filesystem direct vẫn faster cho single agent + single vault. Mình dùng filesystem direct cho 80% use case, MCP server cho 20% advanced workflow (automation, multi-agent).

Port 22360 conflict với app khác xử lý ra sao?

Edit plugin settings đổi port. iansinnott plugin cho phép custom port qua Settings UI. Lưu ý update Claude Code MCP config tương ứng. Nếu chạy multiple vault parallel, mỗi vault một port khác (22361, 22362, etc).

REST API approach tốc độ chậm hơn filesystem bao nhiêu?

100-300ms overhead mỗi tool call do HTTP layer. Với workflow nhiều operation (50+ calls/session), tổng overhead 5-15 giây. Filesystem direct gần như instant. Trade-off chấp nhận được nếu cần Templater hooks chạy.

Setup script automate cho team được không?

Có. Mình dùng Ansible playbook config plugin Local REST API + MCP server cho team 5 người. Mỗi member chạy ansible-playbook setup-mcp.yml lần đầu, config xong trong 5 phút. Repo template lưu trong docs nội bộ team, không public vì chứa config endpoint cụ thể.

MCP servers update có break Claude Code session không?

Có thể. Plugin update spec từ 2024-11-05 sang 2025-x có thể requires Claude Code MCP config update. Best practice: pin plugin version trong CLAUDE.md, test trên test-vault trước khi update production.

Obsidian plugin và external MCP server có conflict không?

Hiếm. Plugin Local REST API (cho REST approach) và external MCP server hoạt động khác layer. Plugin handle HTTP request từ MCP server, server gọi Claude tools. Conflict thường do port, không phải logic. Test trên test-vault trước.

Bạn Bắt Đầu MCP Server Từ Lựa Chọn Nào?

Bắt đầu với KHÔNG dùng MCP server. Filesystem direct cd vault && claude đủ cho 80% use case developer. Setup MCP server chỉ khi có concrete need: multi-agent (Claude + Cursor + Gemini cùng vault), automation script chạy không cần Obsidian mở, hoặc team workflow có shared MCP endpoint.

Khi cần MCP server đầu tiên, thử obsidian-mcp npx setup. Một dòng command, không plugin, không API key. Test 1 tuần thấy giá trị thực sự thì commit lâu dài. Nếu không thấy giá trị, quay lại filesystem direct, không lost gì.

Cluster Obsidian + Claude Code của ongboit gồm pillar setup, Karpathy LLM Wiki story, 3-layer architecture, daily notes workflow, CLAUDE.md 5 templates, PARA folder structure. Bài này (MCP server) là technical layer optional sau khi bạn đã master 6 bài trên. Recommend setup theo thứ tự foundation trước, MCP layer sau.

Tài liệu tham khảo bên ngoài

• Model Context Protocol (Anthropic official), MCP spec gốc.
• iansinnott/obsidian-claude-code-mcp, primary MCP server cho Obsidian.