mcp-obsidian

This MCP server provides direct, secure access to Obsidian vault files without requiring the Obsidian app. It runs as a standard Node.js server that interfaces with your vault on disk, exposing a rich set of MCP tools for searching, reading, writing, and managing notes. Key capabilities include powerful search across notes with context snippets and highlight, metadata extraction, and a specialized discover-mocs tool that maps Maps of Content within your vault to help you navigate knowledge structures. You can integrate this server with tools like Claude Desktop or obsidian.nvim to enable Obsidian-like workflows without the GUI dependency. To start using it, run the server with your vault path, then interact with the available MCP tools (search-vault, get-note-metadata, read-note, write-note, delete-note, and discover-mocs) via the MCP protocol or through the client interfaces that support MCP.

Prerequisites:

• Node.js (LTS version) and npm installed on your machine
• Access to the vault you want to expose via the MCP server

Installation steps:

1. Clone the repository git clone https://github.com/Piotr1215/mcp-obsidian.git cd mcp-obsidian

2. Install dependencies npm install

3. Run the MCP server (provide the path to your Obsidian vault) node src/index.js /path/to/your/vault

4. Verify the server is running (default MCP discovery endpoints or testing clients) Use an MCP client to connect to the server and ensure the vault is accessible

Note: If you publish or deploy this server, ensure proper access controls and network safety to prevent unauthorized filesystem access.

Tips and considerations:

• Security: The server accesses vault files directly on disk. Ensure proper filesystem permissions and network exposure controls to prevent unauthorized access.
• Path validation: The MCP server includes path traversal protection; always specify vault paths and note paths carefully.
• discover-mocs: Use the discover-mocs tool to quickly understand your vault's Maps of Content and navigate large vaults efficiently.
• Context options for search: You can tune contextLines and includeContext when using search-vault to balance performance and context depth.
• Environment variables: If deploying, you may want to configure logging, resource limits, and security headers at the deployment layer; the MCP server itself uses standard Node.js runtime environment variables.
• Versions: Keep Node.js and dependencies updated to benefit from security patches and performance improvements.
• Troubleshooting: If the server fails to access vault files, verify file permissions, ensure the vault path is correct, and check your Node.js version compatibility with the project.