From 2774f67d7dd4790a0744e484f5c66a89c9701466 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 15 Nov 2025 17:14:31 +0000
Subject: [PATCH] docs: add comprehensive guide for installing MCP server
 outside vault (#28)

Added detailed documentation for users who need to install the MCP server binary outside their Obsidian vault directory, particularly for users affected by cloud sync services (OneDrive, Google Drive) that automatically remove executable files.

**New Documentation Includes:**

1. **Step-by-step installation guide:**
   - Creating external installation directory
   - Downloading the correct platform binary
   - Setting executable permissions
   - Manual MCP client configuration

2. **Platform-specific paths:**
   - macOS/Linux: ~/.local/share/obsidian-mcp-tools/bin/
   - Windows: %LOCALAPPDATA%\obsidian-mcp-tools\bin\

3. **Complete configuration examples:**
   - JSON configuration with absolute paths
   - Environment variable setup
   - API key integration

4. **Benefits clearly outlined:**
   - Cloud sync compatibility
   - Binary/data separation
   - Multi-vault support
   - Independent update management

This provides a workaround for issue #28 until native UI support for custom installation paths can be implemented. Users can now manually install the server outside their vault and configure it to work with any MCP client.

Addresses #28
---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index 38c71a8..9bd2ad7 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,66 @@ Clicking the install button will:
   - Windows: %APPDATA%\obsidian-mcp-tools\logs
   - Linux: ~/.local/share/obsidian-mcp-tools/logs
 
+### Installing Server Outside Vault Directory
+
+If you use OneDrive, Google Drive, or another cloud sync service that automatically removes executables, you can manually install the MCP server outside your vault:
+
+#### 1. Create an External Installation Directory
+
+Choose a location outside your vault that won't be synced:
+- **macOS/Linux**: `~/.local/share/obsidian-mcp-tools/bin/`
+- **Windows**: `%LOCALAPPDATA%\obsidian-mcp-tools\bin\`
+
+```bash
+# macOS/Linux
+mkdir -p ~/.local/share/obsidian-mcp-tools/bin
+
+# Windows (PowerShell)
+New-Item -ItemType Directory -Path "$env:LOCALAPPDATA\obsidian-mcp-tools\bin" -Force
+```
+
+#### 2. Download the MCP Server Binary
+
+Download the latest release for your platform from the [releases page](https://github.com/jacksteamdev/obsidian-mcp-tools/releases):
+- **macOS (Intel)**: `mcp-server-macos-x64`
+- **macOS (Apple Silicon)**: `mcp-server-macos-arm64`
+- **Windows**: `mcp-server-windows.exe`
+- **Linux**: `mcp-server-linux`
+
+Move the downloaded binary to your installation directory and make it executable:
+
+```bash
+# macOS/Linux
+chmod +x ~/.local/share/obsidian-mcp-tools/bin/mcp-server
+```
+
+#### 3. Configure Your MCP Client
+
+Manually configure your MCP client to use the external binary location. Edit your MCP client's configuration file:
+
+**For Claude Desktop:**
+
+```json
+{
+  "mcpServers": {
+    "obsidian-mcp-tools": {
+      "command": "/Users/YourUsername/.local/share/obsidian-mcp-tools/bin/mcp-server",
+      "env": {
+        "OBSIDIAN_API_KEY": "your-local-rest-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Replace the `command` path with your actual installation path and `OBSIDIAN_API_KEY` with your Local REST API plugin's API key.
+
+**Benefits of External Installation:**
+- Compatible with cloud sync services that block executables
+- Separates application binaries from document data
+- Single installation can serve multiple vaults (using different API keys)
+- Easier to manage binary updates independently
+
 ## Configuration
 
 After clicking the "Install Server" button in the plugin settings, the plugin will automatically: