Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
npm install @mauricio.wolff/mcp-obsidianA 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.






https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c
1. Install Node.js runtime:
``bash`
# Download from https://nodejs.org (v18.0.0 or later)
# or use a package manager like nvm, brew, apt, etc.
2. Test the server:
If using the published package:
`bash`
npx @modelcontextprotocol/inspector npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault
3. Configure your AI client:
Claude Desktop - Copy this to claude_desktop_config.json:`
json`
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
}
}
}
Claude Code - Copy this to ~/.claude.json:`
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.
4. Test with your AI:
- "List files in my Obsidian vault"
- "Read my note called 'project-ideas.md'"
- "Create a new note with today's date"
Success indicators: Your AI should be able to list files and read notes from your vault.
- ✅ Safe frontmatter parsing and validation using gray-matter
- ✅ Path filtering to exclude .obsidian directory and other system filesread_note
- ✅ Complete MCP toolkit: 11 methods covering all vault operations
- File operations: , write_note, delete_note, move_notelist_directory
- Directory operations: read_multiple_notes
- Batch operations: search_notes
- Search: with content and frontmatter supportget_frontmatter
- Metadata: , update_frontmatter, get_notes_infomanage_tags
- Tag management: (add, remove, list)overwrite
- ✅ Write modes: , append, prepend for flexible content editingprettyPrint: true
- ✅ Tag management: add, remove, and list tags in notes
- ✅ Safe deletion with confirmation requirement to prevent accidents
- ✅ Automatic path trimming to handle whitespace in inputs
- ✅ TypeScript support with Node.js runtime (using tsx for execution)
- ✅ Comprehensive error handling and validation
- ✅ Token-optimized responses: 40-60% smaller responses with minified field names and compact JSON (v0.6.3+)
- ✅ Optional pretty-printing: Set for human-readable debugging
- ✅ Performance optimized: No unnecessary token consumption, efficient for large vaults
- ✅ Zero dependencies: No Obsidian plugins required, works with any vault structure
- Node.js runtime (v18.0.0 or later)
- An Obsidian vault (local directory with .md files)
- MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)
No installation needed! Use npx to run directly:
`bash`
npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault
1. Clone this repository
2. Use the correct Node.js version:
`bash`
nvm use # Uses Node 24 from .nvmrc`
3. Install dependencies with npm:bash`
npm install # Corepack automatically uses npm 10.9.0
4. Test locally with MCP inspector:
`bash`
npx @modelcontextprotocol/inspector npm start /path/to/your/vault
Pro tip: Use MCP Inspector to test all server functionality before configuring with AI clients:
`bashInstall globally for easier access
npm install -g @modelcontextprotocol/inspector
Usage
$3
End users:
`bash
npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault
`Developers:
`bash
npm start /path/to/your/obsidian/vault
`$3
#### Claude Desktop
Add to your Claude Desktop configuration file:
Single Vault:
`json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/MyVault"]
}
}
}
`Multiple Vaults:
`json
{
"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:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.jsonYou can also access this through Claude Desktop → Settings → Developer → Edit Config
#### ChatGPT Desktop
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:
1. Access ChatGPT developer mode (beta feature)
2. Configure MCP servers through the built-in MCP client
3. Create custom connectors for your organization
Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration.
#### Claude Code
Claude Code uses
.claude.json configuration file:User-scoped (recommended):
Edit
~/.claude.json:
`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:
`json
{
"projects": {
"/path/to/your/project": {
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
}
}
}
}
}
`Using Claude Code CLI:
`bash
claude mcp add obsidian --scope user npx @mauricio.wolff/mcp-obsidian /path/to/your/vault
`#### Goose Desktop
On Goose Desktop settings, click Add custom extension, and on the command field add:
`bash
npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault
`#### Other MCP-Compatible Clients (2025)
Confirmed MCP Support:
- IntelliJ IDEA 2025.1+ - Native MCP client support
- Cursor IDE - Built-in MCP compatibility
- Windsurf IDE - Full MCP integration
- Zed, Replit, Codeium, Sourcegraph - In development
- Microsoft Copilot Studio - Native MCP support with one-click server connections
Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.
$3
#### Ask your AI assistant about your notes:
- "What files are in my Obsidian vault?"
- "Read my note called 'project-ideas.md'"
- "Show me all notes with 'AI' in the title"
#### Have your AI assistant help with note management:
- "Create a new note called 'meeting-notes.md' with today's date in the frontmatter"
- "Append today's journal entry to my daily note"
- "Prepend an urgent task to my todo list"
- "Add the tags 'project' and 'urgent' to my task note"
- "List all tags in my research note"
- "Remove the 'draft' tag from my completed article"
- "List all markdown files in my 'Projects' folder"
- "Delete the old draft note 'draft-ideas.md' (with confirmation)"
#### Advanced Use Cases:
- Knowledge Synthesis: "Summarize all my research notes tagged with 'machine-learning' from the last month"
- Project Management: "Update the status in all project notes to 'completed' and add today's date"
- Content Analysis: "Find all notes that mention 'API design' and create a comprehensive guide"
- Smart Tagging: "Review my untagged notes and suggest appropriate tags based on content"
Troubleshooting
$3
#### "command not found: npx"
- Solution: Install Node.js runtime from nodejs.org
- Alternative: Use global install:
npm install -g @mauricio.wolff/mcp-obsidian#### "Usage: node server.ts /path/to/vault"
- Cause: No vault path provided
- Solution: Specify the full path to your Obsidian vault directory
#### "Permission denied" errors
- Cause: Insufficient file system permissions
- Solution: Ensure the vault directory is readable/writable by your user
#### "Path traversal not allowed"
- Cause: Trying to access files outside the vault
- Solution: All file paths must be relative to the vault root
#### AI client not recognizing the server
1. Check the configuration file path is correct for your OS
2. Ensure JSON syntax is valid (use a JSON validator)
3. Restart your AI client after configuration changes
4. Check your AI client's logs for error messages
5. Verify your AI client supports MCP (Model Context Protocol)
#### ".obsidian files still showing up"
- Expected: The path filter automatically excludes
.obsidian/** patterns
- If still seeing them: The filter is working as designed for security$3
Run with error logging:
`bash
npx @mauricio.wolff/mcp-obsidian /path/to/vault 2>debug.log
`$3
- Open an issue on GitHub
- Include your OS, Node.js version, and error messages
- Provide the vault directory structure (without sensitive content)
Testing
Run the test suite:
`bash
npm test
`API Methods
$3
Read a note from the vault with parsed frontmatter.Request:
`json
{
"name": "read_note",
"arguments": {
"path": "project-ideas.md",
"prettyPrint": false
}
}
`Response (optimized for tokens):
`json
{"fm":{"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"}
`Response (with prettyPrint: true):
`json
{
"fm": {
"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"
}
`$3
Write a note to the vault with optional frontmatter and write mode.Write Modes:
-
overwrite (default): Replace entire file content
- append: Add content to the end of existing file
- prepend: Add content to the beginning of existing fileRequest (Overwrite):
`json
{
"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):
`json
{
"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:
`json
{
"message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
}
`$3
List files and directories in the vault.Request:
`json
{
"name": "list_directory",
"arguments": {
"path": "Projects",
"prettyPrint": false
}
}
`Response (optimized):
`json
{"dirs":["AI-Tools","Web-Development"],"files":["project-template.md","roadmap.md"]}
`$3
Delete a note from the vault (requires confirmation for safety).Request:
`json
{
"name": "delete_note",
"arguments": {
"path": "old-draft.md",
"confirmPath": "old-draft.md"
}
}
`Response (Success):
`json
{
"success": true,
"path": "old-draft.md",
"message": "Successfully deleted note: old-draft.md. This action cannot be undone."
}
`Response (Confirmation Failed):
`json
{
"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.$3
Extract only the frontmatter from a note without reading the full content.Request:
`json
{
"name": "get_frontmatter",
"arguments": {
"path": "project-ideas.md",
"prettyPrint": false
}
}
`Response (optimized, returns frontmatter directly):
`json
{"title":"Project Ideas","tags":["projects","brainstorming"],"created":"2023-01-15T10:30:00.000Z"}
`$3
Add, remove, or list tags in a note. Tags are managed in the frontmatter and inline tags are detected.Request (List Tags):
`json
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "list"
}
}
`Request (Add Tags):
`json
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "add",
"tags": ["machine-learning", "ai", "important"]
}
}
`Request (Remove Tags):
`json
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "remove",
"tags": ["draft", "temporary"]
}
}
`Response:
`json
{
"path": "research-notes.md",
"operation": "add",
"tags": ["research", "ai", "machine-learning", "important"],
"success": true,
"message": "Successfully added tags"
}
`$3
Search for notes in the vault by content or frontmatter.Request:
`json
{
"name": "search_notes",
"arguments": {
"query": "machine learning",
"limit": 5,
"searchContent": true,
"searchFrontmatter": false,
"caseSensitive": false,
"prettyPrint": false
}
}
`Response (optimized with minified field names):
`json
[{"p":"ai-research.md","t":"AI Research Notes","ex":"...machine learning...","mc":2,"ln":15}]
`Field names:
-
p = path
- t = title
- ex = excerpt (21 chars context)
- mc = match count
- ln = line number$3
Move or rename a note in the vault.Request:
`json
{
"name": "move_note",
"arguments": {
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"overwrite": false
}
}
`Response:
`json
{
"success": true,
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"message": "Successfully moved note from drafts/article.md to published/article.md"
}
`$3
Read multiple notes in a batch (maximum 10 files).Request:
`json
{
"name": "read_multiple_notes",
"arguments": {
"paths": ["note1.md", "note2.md", "note3.md"],
"includeContent": true,
"includeFrontmatter": true,
"prettyPrint": false
}
}
`Response (optimized, shortened field names):
`json
{"ok":[{"path":"note1.md","frontmatter":{"title":"Note 1"},"content":"# Note 1\n\nContent here..."}],"err":[{"path":"note2.md","error":"File not found"}]}
`Field names:
-
ok = successful reads
- err = failed reads$3
Update frontmatter of a note without changing content.Request:
`json
{
"name": "update_frontmatter",
"arguments": {
"path": "research-note.md",
"frontmatter": {
"status": "completed",
"updated": "2025-09-23"
},
"merge": true
}
}
`Response:
`json
{
"message": "Successfully updated frontmatter for: research-note.md"
}
`$3
Get metadata for notes without reading full content.Request:
`json
{
"name": "get_notes_info",
"arguments": {
"paths": ["note1.md", "note2.md"],
"prettyPrint": false
}
}
`Response (optimized, returns array directly):
`json
[{"path":"note1.md","size":1024,"modified":1695456000000,"hasFrontmatter":true}]
`Security Considerations
This MCP server implements several security measures to protect your Obsidian vault:
$3
- Path Traversal Protection: All file paths are validated to prevent access outside the vault
- Relative Path Enforcement: Paths are normalized and restricted to the vault directory
- Symbolic Link Safety: Resolved paths are checked against vault boundaries$3
- Automatic Exclusions: .obsidian, .git, node_modules, and system files are filtered
- Extension Whitelist: Only .md, .markdown, and .txt files are accessible by default
- Hidden File Protection: Dot files and system directories are automatically excluded$3
- YAML Frontmatter Validation: Frontmatter is parsed and validated before writing
- Function/Symbol Prevention: Dangerous JavaScript objects are blocked from frontmatter
- Data Type Checking: Only safe data types (strings, numbers, arrays, objects) allowed$3
- Least Privilege: Server only accesses the specified vault directory
- Read-Only by Default: Consider running with read-only permissions for sensitive vaults
- Backup Recommended: Always backup your vault before using write operations
- Network Isolation: Server uses stdio transport (no network exposure)$3
- File Content: The server can read/write any allowed file content
- Vault Structure: Directory structure is visible to AI assistants
- File Metadata: Creation times, file sizes, etc. are accessible⚠️ Important: Only grant vault access to trusted AI conversations. The server provides full read/write access to your notes within the security boundaries above.
Architecture
-
server.ts - MCP server entry point
- src/frontmatter.ts - YAML frontmatter handling with gray-matter
- src/filesystem.ts - Safe file operations with path validation
- src/pathfilter.ts - Directory and file filtering
- src/search.ts - Note search functionality with content and frontmatter support
- src/types.ts - TypeScript type definitionsContributing
1. Fork the repository
2. Create a feature branch:
git checkout -b feature-name
3. Make your changes and add tests
4. Ensure all tests pass: npm test`MIT