Obsidian MCP

What is Obsidian MCP about?

Obsidian MCP provides a Model Context Protocol (MCP) server that connects AI assistants (e.g., Claude Desktop) to one or more Obsidian vaults. The server exposes tools for reading, searching, creating, editing, moving, deleting notes, managing directories, and handling tags, giving the assistant full read‑write interaction with your personal knowledge base.

How to use Obsidian MCP?

1. Install Node.js (v20+).
2. Add the server to Claude Desktop configuration (or another MCP‑compatible client) using the npx command:

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["-y", "obsidian-mcp", "/path/to/your/vault", "/path/to/your/vault2"]
       }
     }
   }
   

3. Replace the placeholder paths with absolute paths to your vault(s).
4. Restart Claude Desktop; the hammer icon indicates a successful connection.
5. Use the exposed tools (e.g., read-note, create-note, search-vault) via the AI assistant’s UI or API.

Key Features

• Read and search notes across single or multiple vaults.
• Create new notes and directories.
• Edit, move, and delete existing notes.
• Comprehensive tag management: add, remove, rename, list.
• Multi‑vault support with a list-available-vaults tool.
• Full read‑write access (with explicit user consent).
• Simple installation via npx or Smithery (optional).

Use Cases

• AI‑assisted writing – Generate drafts directly inside your vault and let the model edit or reorganize them.
• Knowledge retrieval – Ask the assistant to fetch specific notes or search for keywords across the vault.
• Tag hygiene – Automatically rename or clean up tags in bulk.
• Project onboarding – Create a pre‑populated folder structure for new projects via AI prompts.
• Backup verification – Use the server to list and compare vault contents before performing bulk operations.

FAQ

Q: Does the server modify my vault automatically? A: Only when you explicitly approve a tool action. All write operations are gated by the assistant’s UI prompts.

Q: Do I need an API key? A: No external API key is required for the server itself; it only needs filesystem access to the specified vault paths.

Q: Can I run multiple vaults simultaneously? A: Yes. Provide additional absolute paths as extra arguments; the list-available-vaults tool helps you choose among them.

Q: What if I encounter permission errors? A: Ensure the user running the server has read/write permissions on the vault directories and that the paths are correct.

Q: How do I view logs for troubleshooting? A: On macOS: ~/Library/Logs/Claude/mcp*.log; on Windows: %APPDATA%\Claude\logs\mcp*.log.

Obsidian MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.

Warning!!!

This MCP has read and write access (if you allow it). Please. PLEASE backup your Obsidian vault prior to using obsidian-mcp to manage your notes. I recommend using git, but any backup method will work. These tools have been tested, but not thoroughly, and this MCP is in active development.

Features

• Read and search notes in your vault
• Create new notes and directories
• Edit existing notes
• Move and delete notes
• Manage tags (add, remove, rename)
• Search vault contents

Requirements

• Node.js 20 or higher (might work on lower, but I haven't tested it)
• An Obsidian vault

Install

Installing Manually

Add to your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "obsidian": {
            "command": "npx",
            "args": ["-y", "obsidian-mcp", "/path/to/your/vault", "/path/to/your/vault2"]
        }
    }
}

Replace /path/to/your/vault with the absolute path to your Obsidian vault. For example:

MacOS/Linux:

"/Users/username/Documents/MyVault"

Windows:

"C:\\Users\\username\\Documents\\MyVault"

Restart Claude for Desktop after saving the configuration. You should see the hammer icon appear, indicating the server is connected.

If you have connection issues, check the logs at:

• MacOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Installing via Smithery

Warning: I am not affiliated with Smithery. I have not tested using it and encourage users to install manually if they can.

To install Obsidian for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install obsidian-mcp --client claude

Development

# Clone the repository
git clone https://github.com/StevenStavrakis/obsidian-mcp
cd obsidian-mcp

# Install dependencies
npm install

# Build
npm run build

Then add to your Claude Desktop configuration:

{
    "mcpServers": {
        "obsidian": {
            "command": "node",
            "args": ["<absolute-path-to-obsidian-mcp>/build/main.js", "/path/to/your/vault", "/path/to/your/vault2"]
        }
    }
}

Available Tools

• read-note - Read the contents of a note
• create-note - Create a new note
• edit-note - Edit an existing note
• delete-note - Delete a note
• move-note - Move a note to a different location
• create-directory - Create a new directory
• search-vault - Search notes in the vault
• add-tags - Add tags to a note
• remove-tags - Remove tags from a note
• rename-tag - Rename a tag across all notes
• manage-tags - List and organize tags
• list-available-vaults - List all available vaults (helps with multi-vault setups)

Documentation

Additional documentation can be found in the docs directory:

• creating-tools.md - Guide for creating new tools
• tool-examples.md - Examples of using the available tools

Security

This server requires access to your Obsidian vault directory. When configuring the server, make sure to:

• Only provide access to your intended vault directory
• Review tool actions before approving them

Troubleshooting

Common issues:

1. Server not showing up in Claude Desktop

   • Verify your configuration file syntax
   • Make sure the vault path is absolute and exists
   • Restart Claude Desktop

2. Permission errors

   • Ensure the vault path is readable/writable
   • Check file permissions in your vault

3. Tool execution failures

   • Check Claude Desktop logs at:
     • macOS: ~/Library/Logs/Claude/mcp*.log
     • Windows: %APPDATA%\Claude\logs\mcp*.log

License

MIT