Obsidian MCP Server

Obsidian MCP Server

Enables MCP clients (e.g., Claude Desktop) to interact with Obsidian vaults seamlessly.

Features

• Multi-Vault Support: Access unlimited Obsidian vaults without per-vault configuration
• Auto-Discovery: Automatically discovers REST API credentials from plugin configuration
• Concurrent-Safe: File locking prevents data corruption during simultaneous access
• Hybrid Access: Filesystem operations (always available) + REST API integration (optional)
• Security-First: Path validation, rate limiting, command allowlist, and secure credential handling
• Zero-Config: Works immediately with filesystem access; REST API features activate when plugin is installed

Installation

From Source (Current)

Currently, installation from source is required:

git clone <repository-url>
cd obsidian-mcp-server
npm install
npm run build

Via NPM (Coming Soon)

Once published to npm, you'll be able to install globally:

npm install -g obsidian-mcp-server

Note: The package is not yet published. Use "From Source" installation for now.

Quick Start

1. Basic Setup (Filesystem Access Only)

The server automatically detects and configures your Obsidian vaults on first run! No manual configuration needed.

What happens automatically:

• Config file is created at ~/.config/mcp-obsidian/config.json (macOS/Linux) or %APPDATA%/mcp-obsidian/config.json (Windows)
• Server scans common locations (Documents, Dropbox, iCloud, etc.) for Obsidian vaults
• Discovered vault paths are automatically added to the configuration
• Ready to use immediately!

Common locations scanned:

• ~/Documents/Obsidian
• ~/Dropbox and subdirectories
• ~/Library/CloudStorage/Dropbox (macOS)
• ~/Library/Mobile Documents/iCloud~md~obsidian (macOS)
• ~/OneDrive/Documents/Obsidian (Windows)

Note: You can override the config location by setting the MCP_OBSIDIAN_CONFIG environment variable.

This enables immediate access to all discovered vaults using filesystem operations.

2. Enable REST API Features (Optional)

Install the Obsidian Local REST API plugin in your vault:

1. Open Obsidian Settings → Community Plugins
2. Browse and install "Local REST API"
3. Enable the plugin
4. The plugin will generate an API key automatically

No additional configuration needed - the server will auto-discover the credentials.

3. Connect to Claude

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"]
    }
  }
}

Note: The env section is optional. If omitted, the server uses the default config location (~/.config/mcp-obsidian/config.json). Only add it if you want to use a custom config path:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "MCP_OBSIDIAN_CONFIG": "/custom/path/to/config.json"
      }
    }
  }
}

Restart Claude Desktop.

Configuration

Most users don't need to configure anything! The server auto-detects your vaults on first run.

Manual Configuration (Optional)

If you need to customize settings or add vaults in non-standard locations, edit ~/.config/mcp-obsidian/config.json:

Minimal Configuration:

{
  "defaultVaultPath": "/Users/yourname/Documents/Obsidian"
}

Full Configuration:

See config.example.json for a complete configuration with all options:

• defaultVaultPath: Base directory containing your vaults
• vaults: Named vault mappings for easy access
• security: Path restrictions, rate limits, allowed hosts/ports
• features: File locking, caching, file watching settings
• logging: Log level and sensitive data sanitization

Named Vaults

For easier access, define named vaults in your config:

{
  "defaultVaultPath": "/Users/yourname/Documents/Obsidian",
  "vaults": {
    "personal": "PersonalVault",
    "work": "WorkVault"
  }
}

Then reference them by name in Claude: "vault": "personal" instead of full paths.

Available Tools

File Operations

• list_vaults: List all accessible vaults
• get_vault_info: Get vault metadata (file count, plugin status)
• list_files: List files in a vault (supports recursive, hidden files)
• get_file: Read file content with optional frontmatter parsing
• write_file: Write or update files with conflict detection
• append_content: Append content to existing files
• search_files: Search with regex, case sensitivity, context
• get_metadata: Extract frontmatter, tags, links, word count

Obsidian Integration (Requires REST API Plugin)

• execute_command: Execute whitelisted Obsidian commands
• open_file: Open files in