mcp-obsidian

This MCP server exposes the following tools and resources to AI assistants:

# 1. Set your Obsidian API key export OBSIDIAN_API_KEY="your-obsidian-rest-api-key" # 2. Add MCP server and test (Claude Code) claude mcp add obsidian -- bunx -y @oleksandrkucherenko/mcp-obsidian claude "Search my Obsidian vault for monitoring tools, summarize findings" # 2. Alternative: Codex CLI codex mcp add obsidian --command "bunx -y @oleksandrkucherenko/mcp-obsidian" codex "Find notes about logging frameworks and create a comparison table"

Example use-case:"Find all tools in my Obsidian vault for tracking logs and metrics, make a summary report"— the AI searches your vault, finds notes about OpenTelemetry, Datadog, Prometheus, etc., and generates a structured summary.

For other CLI tools (Gemini, OpenCode, Kilo Code, Copilot), seeManual Testing Guide.

{ "mcpServers": { "obsidian": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian", "--rm", "-i", // Keep STDIN open for stdio transport "-p", "3000:3000", "-e", "API_KEY", "-e", "API_URLS", "-e", "DEBUG", // for logs "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", // JSON array - automatically tests and selects fastest URL "API_URLS": "[\"https://127.0.0.1:27124\",\"https://172.26.32.1:27124\",\"https://host.docker.internal:27124\"]", "DEBUG": "mcp:" } } } }

# Automatically determine WSL gateway IP export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}') # Configure with multiple fallback URLs API_URLS='["https://127.0.0.1:27124", "https://'$WSL_GATEWAY_IP':27124", "https://host.docker.internal:27124"]'

{ "mcpServers": { "obsidian-http": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian-http", "--rm", "-p", "3000:3000", "-e", "API_KEY", "-e", "API_URLS", "-e", "MCP_HTTP_PATH", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", "API_URLS": "[\"https://127.0.0.1:27124\",\"https://172.26.32.1:27124\",\"https://host.docker.internal:27124\"]", "MCP_HTTP_PATH": "/mcp" // endpoint path (default is: /mcp) } } } }

# Automatically determine WSL gateway IP export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}') # Configure with multiple fallback URLs API_URLS='["https://127.0.0.1:27124", "https://'$WSL_GATEWAY_IP':27124", "https://host.docker.internal:27124"]' # run MCP server on docker separately from IDE docker run --name mcp-obsidian-http --rm \ -p 3000:3000 \ -e API_KEY="<secret_key>" \ -e API_URLS="${API_URLS}" \ -e MCP_HTTP_TOKEN=<your-secret-token-here> \ ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

{ "mcpServers": { "obsidian": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer <your-secret-token-here>" } } } }

Authorization: Bearer your-secret-token-here

{ "mcpServers": { "obsidian": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian-windsurf", "--interactive", "--rm", "-e", "API_KEY", "-e", "API_URLS", "-e", "DEBUG", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", "API_URLS": "[\"https://127.0.0.1:27124\",\"https://172.26.32.1:27124\"]", "DEBUG": "mcp:" // default: disabled logs } } } }

- --rm- Automatically remove the container and its associated anonymous volumes when it exits
- -i, --interactive- Keep STDIN open
- -e, --env- Set environment variables
- --name string- Assign a name to the container
- -p, --publish- Publish container port to host
- NPM Package Releases
- Docker Image Releases

{ "mcpServers": { "obsidian": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian", "--rm", "-i", "-e", "API_KEY", "-e", "API_HOST", "-e", "API_PORT", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", "API_HOST": "https://172.26.32.1", // single URL without failover "API_PORT": "27124" } } } }

Note:Single-URL configuration does not provide automatic failover or health monitoring. UseAPI_URLSfor production deployments.

When HTTP transport is enabled, the server exposes a health check endpoint at/health:

{ "status": "healthy", "timestamp": "2025-01-12T12:00:00.000Z", "transport": "http", "authEnabled": false }

For comprehensive health status including Obsidian API connection and all transports, you can use thegetHealthStatus()function which returns:

{ "healthy": true, "obsidian": { "connected": true, "url": "https://obsidian:27124", "lastCheck": 1705065600000 }, "transports": { "stdio": { "running": true, "enabled": true }, "http": { "running": true, "enabled": true } }, "uptime": 3600, "timestamp": 1705065600000 }

This section shows how to configure popular AI CLI tools to use the MCP Obsidian server.

# MacOs or Linux curl -fsSL https://bun.sh/install | bash # Windows powershell -c "irm bun.sh/install.ps1 | iex"

# Create mcp.json configuration cat > mcp.json << 'EOF' { "mcpServers": { "obsidian": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "env": { "API_KEY": "<your-obsidian-api-key>", "API_URLS": "[\"https://host.docker.internal:27124\"]" } } } } EOF # Run Claude with MCP config claude --mcp-config ./mcp.json

cat > mcp.json << 'EOF' { "mcpServers": { "obsidian": { "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "API_KEY": "<your-obsidian-api-key>", "API_URLS": "[\"https://127.0.0.1:27124\"]" } } } } EOF claude --mcp-config ./mcp.json

gemini mcp add \ -e API_KEY=<your-obsidian-api-key> \ -e API_URLS='["https://host.docker.internal:27124"]' \ obsidian \ docker run --rm -i ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

gemini mcp add \ -e API_KEY=<your-obsidian-api-key> \ -e API_URLS='["https://127.0.0.1:27124"]' \ obsidian \ bunx -y @oleksandrkucherenko/mcp-obsidian

gemini mcp add --transport http obsidian-http http://localhost:3000/mcp

gemini mcp list gemini mcp remove obsidian

Createopencode.jsonin your project root:

{ "mcp": { "obsidian": { "type": "local", "command": ["docker", "run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "environment": { "API_KEY": "{env:API_KEY}", "API_URLS": "[\"https://host.docker.internal:27124\"]" }, "enabled": true } } }

{ "mcp": { "obsidian": { "type": "local", "command": ["bunx", "-y", "@oleksandrkucherenko/mcp-obsidian"], "environment": { "API_KEY": "{env:API_KEY}", "API_URLS": "[\"https://127.0.0.1:27124\"]" }, "enabled": true } } }

{ "mcp": { "obsidian-http": { "type": "remote", "url": "http://localhost:3000/mcp", "enabled": true } } }

Create.kilocode/mcp.jsonin your project or~/.kilocode/cli/global/settings/mcp_settings.jsonglobally:

{ "mcpServers": { "obsidian": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "env": { "API_KEY": "<your-obsidian-api-key>", "API_URLS": "[\"https://host.docker.internal:27124\"]" } } } }

{ "mcpServers": { "obsidian": { "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "API_KEY": "<your-obsidian-api-key>", "API_URLS": "[\"https://127.0.0.1:27124\"]" } } } }

{ "mcpServers": { "obsidian-http": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer <your-token>" } } } }

# Register MCP server codex mcp add obsidian \ --command "docker run --rm -i -e API_KEY -e API_URLS ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" \ --env API_KEY=<your-obsidian-api-key> \ --env 'API_URLS=["https://host.docker.internal:27124"]'

codex mcp add obsidian \ --command "bunx -y @oleksandrkucherenko/mcp-obsidian" \ --env API_KEY=<your-obsidian-api-key> \ --env 'API_URLS=["https://127.0.0.1:27124"]'

Create~/.copilot/mcp-config.json(or.copilot/mcp-config.jsonin repo root):

{ "mcpServers": { "obsidian": { "type": "local", "command": "docker", "args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "env": { "API_KEY": "${OBSIDIAN_API_KEY}", "API_URLS": "[\"https://host.docker.internal:27124\"]" }, "tools": [""] } } }

{ "mcpServers": { "obsidian": { "type": "local", "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "API_KEY": "${OBSIDIAN_API_KEY}", "API_URLS": "[\"https://127.0.0.1:27124\"]" }, "tools": [""] } } }

Note:Copilot CLI v0.0.340+ requires${VAR}syntax for environment variable expansion. SetOBSIDIAN_API_KEYin your shell before running.

For detailed testing and verification, seeManual Testing Guide.

- RunObsidian Desktop Applicationand enableLocal REST APIin Settings.

# windows CMD, verify that port is listening (that rest api is running) netstat -an | findstr 27124 # Expected output: # TCP 0.0.0.0:27124 0.0.0.0:0 LISTENING # Verify that Obsidian Local REST API is working curl --insecure https://localhost:27124 wget --no-check-certificate -S https://localhost:27124 http --verify=no https://localhost:27124

{ "status": "OK", "manifest": { "id": "obsidian-local-rest-api", "name": "Local REST API", "version": "3.2.0", "minAppVersion": "0.12.0", "description": "Get, change or otherwise interact with your notes in Obsidian via a REST API.", "author": "Adam Coddington", "authorUrl": "https://coddingtonbear.net/", "isDesktopOnly": true, "dir": ".obsidian/plugins/obsidian-local-rest-api" }, "versions": { "obsidian": "1.8.10", "self": "3.2.0" }, "service": "Obsidian Local REST API", "authenticated": false }

graph LR subgraph "Windows Machine" obs("Obsidian Application") subgraph "WSL2" subgraph "Ubuntu" subgraph "Docker" mcp("mcp-obsidian:latest") end end end firewall(["Windows Firewall"]) -->|27124| obs mcp -->|https://$WSL_GATEWAY_IP:27124| firewall IDE -.->|MCP Server Tools| mcp end

export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}') echo $WSL_GATEWAY_IP # expected something like: 172.26.32.1 # Verify that Obsidian Local REST API is working curl --insecure https://$WSL_GATEWAY_IP:27124 wget --no-check-certificate -S https://$WSL_GATEWAY_IP:27124 http --verify=no https://$WSL_GATEWAY_IP:27124

# Windows Defender Firewall / Inbound Rules. Press Win+R and type WF.msc or firewall.cpl WF.msc firewall.cpl # and then press 'Advanced settings'

Or Run in Windows PowerShell as Administrator:

# Add firewall rule to allow port 27124 (Run in Admin PowerShell) New-NetFirewallRule -DisplayName "WSL2 Obsidian REST API" -Direction Inbound -LocalPort 27123,27124 -Protocol TCP -Action Allow

# check firewall rules (CMD) that manage 27124 port netsh advfirewall firewall show rule name=all | findstr /C:"Rule Name" /C:"LocalPort" /C:"RemotePort" | findstr /C:"27124" # display rules that has WSL2 keyword in own name netsh advfirewall firewall show rule name=all | grep -A 13 WSL2 # display rule definition by port number (4 line after, 9 lines before) netsh advfirewall firewall show rule name=all | grep -A 4 -B 9 27124

Execute in Windows PowerShell as Administrator:

# Temporarily turn off firewall (for testing ONLY, not recommended for regular use) Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False # Restore Firewall state Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled True

Verify Connectivity on BusyBox Container

These steps allow us to confirm that the network setup is correct and the container can connect to the Local REST API.

Execute inside the WSL2 Ubuntu terminal:

export WSL_GATEWAY_IP=$(ip route | grep default | awk '{print $3}') echo "Windows host IP from WSL2: $WSL_GATEWAY_IP" # Output: # Windows host IP from WSL2: 172.26.32.1 # run docker container to verify the connectivity from Docker inside docker run --rm -it --network=host busybox sh # inside the container run: which wget # /bin/wget export WINDOWS_HOST_IP="172.26.32.1" echo $WINDOWS_HOST_IP # 172.26.32.1 # try to connect to the Local REST API wget -qO- --no-check-certificate "https://$WINDOWS_HOST_IP:27124" wget -qO- --no-check-certificate https://172.26.32.1:27124

MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.

Integrates Model Context Protocol (MCP) with Obsidian, allowing AI assistants to interact with your notes and vault.

A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.

A service for reading, writing, and managing markdown documentation with frontmatter metadata.

Connect your AI assistant to your personal knowledge base. Search, save links, create notes and to-dos. AI processes everything automatically.

An MCP server for interacting with Obsidian notes. Requires the OBSIDIAN_VAULT_PATH environment variable to be set.

Interact with your Obsidian vault using natural language.

Interact with your Obsidian vault using the Local REST API plugin, enabling LLMs to access and manage your notes.

Interact with your Obsidian notes and vaults using the Local REST API plugin.

A server for interacting with your Obsidian vault.