Obsidian Web

The obsidian-web-mcp MCP server provides read and write access to your Obsidian vault over HTTPS with real authentication.

Most Obsidian MCP servers run locally via stdio. That approach works when your vault and the MCP client share the same machine.

obsidian-web-mcp runs as a persistent HTTP service with OAuth 2.0 authentication and a Cloudflare Tunnel. This lets Claude (or any MCP client) reach your vault from your desktop, your phone, or any network without exposing your machine directly to the internet.

Features

• The server enforces OAuth 2.0 authorization code flow with PKCE for initial client authentication.
• The system validates bearer tokens on every subsequent MCP tool call.
• The application routes outbound-only encrypted connections through a Cloudflare Tunnel.
• The filesystem layer blocks path traversal attempts involving symlinks or null byte injection.
• The server restricts access to dotfiles like .obsidian and .git.
• The write operations use a write-to-temp-then-rename pattern for atomic file replacement.
• The system caps file writes at 1MB per file.
• The batch operations process a maximum of 20 files per request.
• The search tool returns a maximum of 50 matches per query.
• The delete function moves files to the .trash directory and requires an explicit confirmation parameter.
• The frontmatter index watches for filesystem changes via watchdog to update automatically.

Use Cases

• Access a local Obsidian vault from the Claude web interface on a different computer.
• Query personal notes from the Claude mobile application on a smartphone.
• Update YAML frontmatter fields across multiple files simultaneously.
• Search the entire vault for specific text strings using ripgrep.
• Filter notes based on specific YAML frontmatter field values or existence.
• Read multiple markdown files in a single batch operation.
• Move or rename directories within the vault structure.
• Soft-delete outdated notes by moving them to the trash directory.

How To Use It

Prerequisites

• Python 3.12 or higher
• uv (recommended) or pip
• An existing Obsidian vault directory
• cloudflared (required only for remote access)
• A domain managed by Cloudflare (required only for remote access)

Configuration Variables

All configuration uses environment variables. The server reads these at startup.

Generate tokens with:

python -c "import secrets; print(secrets.token_hex(32))"

Local Development

Clone the repository and enter the directory:

git clone https://github.com/yourname/obsidian-web-mcp.git
cd obsidian-web-mcp

Generate the required tokens:

export VAULT_MCP_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")
export VAULT_OAUTH_CLIENT_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")

Point the server to your vault:

export VAULT_PATH="$HOME/Obsidian/MyVault"

Start the server:

uv run vault-mcp

The server starts on port 8420 by default. It serves MCP over Streamable HTTP at /mcp/.

Connecting to Claude

Claude desktop and mobile apps can connect to remote MCP servers via OAuth.

1. Start the server (locally or behind a tunnel).
2. Open Claude and navigate to Settings > Integrations > Add Integration.
3. Enter your server URL. For local use, enter http://localhost:8420. For remote use, enter your tunnel hostname (for example, https://vault-mcp.yourdomain.com).
4. Enter the OAuth client ID and client secret you configured.
5. Claude discovers the OAuth endpoints automatically and opens a browser window.
6. The server auto-approves the authorization (single-user model) and redirects back.
7. Claude now has access to all nine vault tools on desktop and mobile.

Tools Reference

The server exposes nine tools. Each tool enforces path security, authentication, and safety limits.

vault_read

Reads a single file and returns content, metadata, and parsed YAML frontmatter.

• Parameters: path (string) – relative path within the vault.
• Returns: file content, frontmatter dictionary, and file metadata.

vault_batch_read

Reads multiple files in one call.

• Parameters: paths (list of strings) – relative paths within the vault.
• Returns: a dictionary keyed by path with content and frontmatter for existing files; missing files are omitted with an error entry.

vault_write

Writes content to a file with optional frontmatter merging.

• Parameters:
• path (string) – relative path within the vault.
• content (string) – file body content.
• frontmatter (dictionary, optional) – YAML frontmatter fields to merge.
• Behavior: creates parent directories if they do not exist. Merges frontmatter with existing frontmatter when present. Uses atomic write.

vault_batch_frontmatter_update

Updates YAML frontmatter fields on multiple files without modifying body content.

• Parameters:
• updates (list of objects) – each object contains path and frontmatter dictionary.
• Behavior: preserves existing frontmatter fields not mentioned in the update. Leaves file body unchanged. Uses atomic write for each file.

vault_search

Performs full-text search across vault files.

• Parameters:
• query (string) – search term or ripgrep pattern.
• max_results (integer, optional, default 50) – maximum number of matches.
• Behavior: uses ripgrep when available on the system; falls back to Python search otherwise. Returns file paths with surrounding context lines.

vault_search_frontmatter

Queries the in-memory frontmatter index by field value, substring, or field existence.

• Parameters:
• field (string) – frontmatter field name.
• value (string, optional) – exact value to match.
• substring (string, optional) – substring to search within the field value.
• exists (boolean, optional) – when true, returns files where the field exists regardless of value.
• Behavior: the index updates automatically via watchdog filesystem watcher. Returns a list of file paths matching the criteria.

vault_list

Lists directory contents with configurable depth and filtering.

• Parameters:
• path (string, optional, default “”) – directory path relative to vault root.
• depth (integer, optional, default 1) – recursion depth (0 for only the directory itself).
• glob (string, optional) – glob pattern to filter results.
• include_files (boolean, optional, default True) – whether to include files.
• include_directories (boolean, optional, default True) – whether to include subdirectories.
• Returns: list of file and directory entries with relative paths.

vault_move

Moves or renames a file or directory within the vault.

• Parameters:
• source (string) – relative path of the existing file or directory.
• destination (string) – relative path for the new location.
• Behavior: works on both files and directories. Validates that the destination stays within the vault root.

vault_delete

Soft-deletes a file by moving it to .trash/.

• Parameters:
• path (string) – relative path of the file.
• confirm (boolean) – must be set to true to execute the deletion.
• Behavior: moves the file to .trash/ inside the vault. Does not delete directories. Requires explicit confirmation as a safety gate.

Remote Access with Cloudflare Tunnel

Install cloudflared:

brew install cloudflare/cloudflare/cloudflared

Set your hostname and run the interactive setup script:

export VAULT_MCP_HOSTNAME="vault-mcp.yourdomain.com"
./scripts/setup-tunnel.sh

The script authenticates with Cloudflare, creates a tunnel, writes the configuration, and sets up the DNS record.

Add your tunnel hostname to the allowed_hosts list in server.py:

allowed_hosts=[
    "127.0.0.1:*",
    "localhost:*",
    "[::1]:*",
    "vault-mcp.yourdomain.com",
],

This step bypasses the MCP library’s DNS rebinding protection for your domain.

Production Deployment on macOS

Use launchd to run both the MCP server and the Cloudflare Tunnel as persistent background services that start at login and restart on failure.

Copy the plist templates to the LaunchAgents directory:

cp scripts/launchd/com.example.vault-mcp.plist ~/Library/LaunchAgents/
cp scripts/launchd/com.example.cloudflared-vault.plist ~/Library/LaunchAgents/

Edit each plist and replace the placeholder tokens:

• REPLACE_WITH_UV_PATH – path to the uv binary (run which uv)
• REPLACE_WITH_PROJECT_PATH – absolute path to the project directory
• REPLACE_WITH_VAULT_PATH – absolute path to your Obsidian vault
• REPLACE_WITH_TOKEN – your VAULT_MCP_TOKEN value
• REPLACE_WITH_OAUTH_SECRET – your VAULT_OAUTH_CLIENT_SECRET value
• REPLACE_WITH_HOME – your home directory (for example, /Users/yourname)
• REPLACE_WITH_CLOUDFLARED_PATH – path to the cloudflared binary (run which cloudflared)

Load the services:

launchctl load ~/Library/LaunchAgents/com.example.vault-mcp.plist
launchctl load ~/Library/LaunchAgents/com.example.cloudflared-vault.plist

Both services are configured with RunAtLoad (start at login) and KeepAlive (restart on failure). They survive reboots.

Verify the services are running:

launchctl list | grep vault

Test the server responds:

curl -s http://localhost:8420/.well-known/oauth-authorization-server

Check logs if needed:

tail -f ~/Library/Logs/vault-mcp-error.log

Testing

Run the test suite with pytest:

uv run pytest tests/ -v

FAQs

Q: Does this server work with Obsidian Sync?
A: Yes. All writes use atomic file replacement (write-to-temp-then-rename). This prevents Obsidian Sync from ever seeing a partially-written file.

Q: What happens if someone tries to access files outside the vault?
A: The server blocks path traversal attacks at the filesystem layer. Every file operation resolves the path against the vault root directory and rejects any attempt to escape it.

Q: How does the frontmatter index stay up to date?
A: The server uses watchdog to watch for filesystem changes. When a file is created, modified, or deleted, the index updates automatically.

Q: Is there a limit on file sizes or batch operations?
A: Yes. Writes are capped at 1MB per file. Batch operations are limited to 20 files per request. Search results return at most 50 matches.