@mauricio.wolff/mcp-obsidian
Advanced tools
Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
A universal AI bridge for Obsidian vaults using the Model Context Protocol (MCP) standard. Connect any MCP-compatible AI assistant to your knowledge base - works with Claude, ChatGPT, and future AI tools. This server provides safe read/write access to your notes while preventing YAML frontmatter corruption.
Works with any MCP-compatible AI assistant including Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), IntelliJ IDEA 2025.1+, Cursor IDE, Windsurf IDE, and future AI platforms that adopt the MCP standard.
https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c
Install Node.js runtime:
# Download from https://nodejs.org (v18.0.0 or later)
# or use a package manager like nvm, brew, apt, etc.
Test the server:
If using the published package:
npx @modelcontextprotocol/inspector npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault
Configure your AI client:
Claude Desktop - Copy this to claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
}
}
}
Claude Code - Copy this to ~/.claude.json:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"],
"env": {}
}
}
}
Replace /path/to/your/vault with your actual Obsidian vault path.
For other platforms, see detailed configuration guides below.
Test with your AI:
Success indicators: Your AI should be able to list files and read notes from your vault.
Built on the open Model Context Protocol standard, MCP-Obsidian is not locked to any single AI provider. As more AI assistants adopt MCP, your investment in this tool grows more valuable. Today it works with Claude and ChatGPT - tomorrow it will work with whatever AI tools emerge.
Instead of waiting for each AI company to build Obsidian integrations, MCP-Obsidian provides a universal adapter that works with any MCP-compatible assistant. One tool, endless possibilities.
MCP is an open protocol. You're not tied to any specific vendor or platform. Your notes remain yours, accessible through any compatible AI assistant.
.obsidian directory and other system filesread_note, write_note, delete_note, move_notelist_directoryread_multiple_notessearch_notes with content and frontmatter supportget_frontmatter, update_frontmatter, get_notes_infomanage_tags (add, remove, list)overwrite, append, prepend for flexible content editing.md files)No installation needed! Use npx to run directly:
npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault
npm install
npx @modelcontextprotocol/inspector npm start /path/to/your/vault
Pro tip: Use MCP Inspector to test all server functionality before configuring with AI clients:
# Install globally for easier access
npm install -g @modelcontextprotocol/inspector
# Test with any vault
mcp-inspector npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault
End users:
npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault
Developers:
npm start /path/to/your/obsidian/vault
Add to your Claude Desktop configuration file:
Single Vault:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/MyVault"]
}
}
}
Multiple Vaults:
{
"mcpServers": {
"obsidian-personal": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/PersonalVault"]
},
"obsidian-work": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/WorkVault"]
}
}
}
Configuration File Locations:
~/Library/Application Support/Claude/claude_desktop_config.jsonC:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonYou can also access this through Claude Desktop → Settings → Developer → Edit Config
Requirements: ChatGPT Enterprise, Education, or Team subscription (not available for individual Plus users)
ChatGPT uses MCP through Deep Research and developer mode. Configuration is done through the ChatGPT interface:
Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration.
Claude Code uses .claude.json configuration file:
User-scoped (recommended):
Edit ~/.claude.json:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"],
"env": {}
}
}
}
Project-scoped:
Edit .claude.json in your project or add to the projects section:
{
"projects": {
"/path/to/your/project": {
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
}
}
}
}
}
Using Claude Code CLI:
claude mcp add obsidian --scope user npx @mauricio.wolff/mcp-obsidian /path/to/your/vault
On Goose Desktop settings, click Add custom extension, and on the command field add:
npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault
Confirmed MCP Support:
Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.
npm install -g @mauricio.wolff/mcp-obsidian.obsidian/** patternsRun with error logging:
npx @mauricio.wolff/mcp-obsidian /path/to/vault 2>debug.log
Run the test suite:
npm test
read_noteRead a note from the vault with parsed frontmatter.
Request:
{
"name": "read_note",
"arguments": {
"path": "project-ideas.md"
}
}
Response:
{
"path": "project-ideas.md",
"frontmatter": {
"title": "Project Ideas",
"tags": ["projects", "brainstorming"],
"created": "2023-01-15T10:30:00.000Z"
},
"content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
write_noteWrite a note to the vault with optional frontmatter and write mode.
Write Modes:
overwrite (default): Replace entire file contentappend: Add content to the end of existing fileprepend: Add content to the beginning of existing fileRequest (Overwrite):
{
"name": "write_note",
"arguments": {
"path": "meeting-notes.md",
"content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
"frontmatter": {
"title": "Team Meeting Notes",
"date": "2023-12-01",
"tags": ["meetings", "team"]
},
"mode": "overwrite"
}
}
Request (Append):
{
"name": "write_note",
"arguments": {
"path": "daily-log.md",
"content": "\n\n## 3:00 PM Update\n- Completed project review\n- Started new feature",
"mode": "append"
}
}
Response:
{
"message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
}
list_directoryList files and directories in the vault.
Request:
{
"name": "list_directory",
"arguments": {
"path": "Projects"
}
}
Response:
{
"path": "Projects",
"directories": [
"AI-Tools",
"Web-Development"
],
"files": [
"project-template.md",
"roadmap.md"
]
}
delete_noteDelete a note from the vault (requires confirmation for safety).
Request:
{
"name": "delete_note",
"arguments": {
"path": "old-draft.md",
"confirmPath": "old-draft.md"
}
}
Response (Success):
{
"success": true,
"path": "old-draft.md",
"message": "Successfully deleted note: old-draft.md. This action cannot be undone."
}
Response (Confirmation Failed):
{
"success": false,
"path": "old-draft.md",
"message": "Deletion cancelled: confirmation path does not match. For safety, both 'path' and 'confirmPath' must be identical."
}
⚠️ Safety Note: The confirmPath parameter must exactly match the path parameter to proceed with deletion. This prevents accidental deletions.
get_frontmatterExtract only the frontmatter from a note without reading the full content.
Request:
{
"name": "get_frontmatter",
"arguments": {
"path": "project-ideas.md"
}
}
Response:
{
"path": "project-ideas.md",
"frontmatter": {
"title": "Project Ideas",
"tags": ["projects", "brainstorming"],
"created": "2023-01-15T10:30:00.000Z"
}
}
manage_tagsAdd, remove, or list tags in a note. Tags are managed in the frontmatter and inline tags are detected.
Request (List Tags):
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "list"
}
}
Request (Add Tags):
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "add",
"tags": ["machine-learning", "ai", "important"]
}
}
Request (Remove Tags):
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "remove",
"tags": ["draft", "temporary"]
}
}
Response:
{
"path": "research-notes.md",
"operation": "add",
"tags": ["research", "ai", "machine-learning", "important"],
"success": true,
"message": "Successfully added tags"
}
search_notesSearch for notes in the vault by content or frontmatter.
Request:
{
"name": "search_notes",
"arguments": {
"query": "machine learning",
"limit": 5,
"searchContent": true,
"searchFrontmatter": false,
"caseSensitive": false
}
}
Response:
{
"query": "machine learning",
"resultCount": 3,
"results": [
{
"path": "ai-research.md",
"title": "AI Research Notes",
"excerpt": "...machine learning algorithms are...",
"matchCount": 2,
"lineNumber": 15
}
]
}
move_noteMove or rename a note in the vault.
Request:
{
"name": "move_note",
"arguments": {
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"overwrite": false
}
}
Response:
{
"success": true,
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"message": "Successfully moved note from drafts/article.md to published/article.md"
}
read_multiple_notesRead multiple notes in a batch (maximum 10 files).
Request:
{
"name": "read_multiple_notes",
"arguments": {
"paths": ["note1.md", "note2.md", "note3.md"],
"includeContent": true,
"includeFrontmatter": true
}
}
Response:
{
"successful": [
{
"path": "note1.md",
"frontmatter": {"title": "Note 1"},
"content": "# Note 1\n\nContent here..."
}
],
"failed": [
{
"path": "note2.md",
"error": "File not found"
}
],
"summary": {
"successCount": 1,
"failureCount": 1
}
}
update_frontmatterUpdate frontmatter of a note without changing content.
Request:
{
"name": "update_frontmatter",
"arguments": {
"path": "research-note.md",
"frontmatter": {
"status": "completed",
"updated": "2025-09-23"
},
"merge": true
}
}
Response:
{
"message": "Successfully updated frontmatter for: research-note.md"
}
get_notes_infoGet metadata for notes without reading full content.
Request:
{
"name": "get_notes_info",
"arguments": {
"paths": ["note1.md", "note2.md"]
}
}
Response:
{
"notes": [
{
"path": "note1.md",
"size": 1024,
"modified": 1695456000000,
"hasFrontmatter": true
}
],
"count": 1
}
This MCP server implements several security measures to protect your Obsidian vault:
.obsidian, .git, node_modules, and system files are filtered.md, .markdown, and .txt files are accessible by default⚠️ Important: Only grant vault access to trusted AI conversations. The server provides full read/write access to your notes within the security boundaries above.
server.ts - MCP server entry pointsrc/frontmatter.ts - YAML frontmatter handling with gray-mattersrc/filesystem.ts - Safe file operations with path validationsrc/pathfilter.ts - Directory and file filteringsrc/search.ts - Note search functionality with content and frontmatter supportsrc/types.ts - TypeScript type definitionsgit checkout -b feature-namenpm testMIT
FAQs
Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
The npm package @mauricio.wolff/mcp-obsidian receives a total of 170 weekly downloads. As such, @mauricio.wolff/mcp-obsidian popularity was classified as not popular.
We found that @mauricio.wolff/mcp-obsidian demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket now integrates with Bun 1.3’s Security Scanner API to block risky packages at install time and enforce your organization’s policies in local dev and CI.
Security News
Python 3.14 adds template strings, deferred annotations, and subinterpreters, plus free-threaded mode, an experimental JIT, and Sigstore verification.
Security News
Former RubyGems maintainers have launched The Gem Cooperative, a new community-run project aimed at rebuilding open governance in the Ruby ecosystem.