MCP Obsidian Server

Quick setup guide for running the MCP Obsidian server

NPM NPM GitHub Docker GitHub Docker (Docker Hub) Ask DeepWiki

Latest Screenshots

Loading screenshots...

Step 1: Set Up Obsidian

Install and run Obsidian Desktop Application and enable the Local REST API plugin in Settings.

Make sure to configure the API to listen on all interfaces (not just localhost), which is critical for WSL2 setup.

Obsidian Local REST API Setup

Important: Copy the API Key from Obsidian Settings, you'll need it for MCP configuration.

Step 2: Configure MCP

Create or update your MCP configuration file with one of the following options:

Option A: Docker (Recommended)

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

Option B: NPX/Bunx

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

Configuration Notes:

  • Replace <your-obsidian-api-key> with the API Key you copied from Obsidian.
  • API_URLS is a JSON array of URLs. You can specify multiple URLs for automatic failover.
  • Docker uses host.docker.internal to reach the host machine.
  • NPX/Bunx runs locally, so use 127.0.0.1 or localhost.
  • For WSL2: use ["https://127.0.0.1:27124", "https://172.26.32.1:27124"] (replace with your Windows host IP).
  • DEBUG is optional - remove it to disable verbose logging.

Step 3: Verify REST API Connection

On Windows:

# Verify that the port is listening
netstat -an | findstr 27124 # Windows CMD

# Test the API connection
curl --insecure https://localhost:27124

On WSL2 (Ubuntu):

# Get Windows host IP
export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}')
echo $WSL_GATEWAY_IP

# Test the API connection
curl --insecure https://$WSL_GATEWAY_IP:27124

On Linux:

# check is port is listening
ss -tuln | grep ':27124'

# Test the API connection
wget --no-check-certificate -S https://localhost:27124

On MacOS:

# check is port is listening
sudo lsof -iTCP:27124 -sTCP:LISTEN

# Test the API connection (Httpie)
http --verify=no https://localhost:27124

Expected successful response:

{
  "status": "OK",
  "manifest": {
    "id": "obsidian-local-rest-api",
    "name": "Local REST API",
    /* other manifest details... */
  },
  "service": "Obsidian Local REST API",
  "authenticated": false
}

Step 4: Check Firewall Settings (Windows)

Ensure your firewall allows connections on port 27124:

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

Step 5: Run the MCP Server (without IDE)

You can now run the MCP server using Docker:

docker run --name mcp-obsidian-windsurf \
  --interactive \
  --rm \
  -e API_KEY="your-api-key" \
  -e API_HOST="https://your-host-ip" \
  -e API_PORT="27124" \
  -e DEBUG="mcp:*" \
  ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

Docker arguments explained:

  • --rm - Automatically remove the container when it exits
  • --interactive - Keep STDIN open
  • -e, --env - Set environment variables

Step 6: Configure Your AI CLI Tool

Configure your preferred AI CLI tool to use the MCP Obsidian server. Choose between Docker-hosted or NPX/Bunx-hosted versions.

Claude Code CLI

Docker:

{
  "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\"]"
      }
    }
  }
}

NPX/Bunx:

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

Save as mcp.json and run: claude --mcp-config ./mcp.json

Gemini CLI

Docker:

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

NPX/Bunx:

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

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

OpenCode CLI

Create opencode.json in your project root:

Docker:

{
  "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
    }
  }
}

NPX/Bunx:

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

Kilo Code CLI

Create .kilocode/mcp.json in your project:

Docker:

{
  "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\"]"
      }
    }
  }
}

NPX/Bunx:

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

Codex CLI

Docker:

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"]'

NPX/Bunx:

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

GitHub Copilot CLI

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

Docker:

{
  "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": ["*"]
    }
  }
}

NPX/Bunx:

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

Copilot CLI v0.0.340+ requires ${VAR} syntax for env expansion. Set OBSIDIAN_API_KEY in your shell.

Quick Reference

CLI Tool Config File Docker HTTP
Claude Codemcp.json✅✅
Geminisettings.json✅✅
OpenCodeopencode.json✅✅
Kilo Code.kilocode/mcp.json✅✅
CodexCLI commands✅✅
Copilot~/.copilot/mcp-config.json✅✅

For detailed testing, see Manual Testing Guide.

Troubleshooting

Connectivity Issues

To test connectivity from a Docker container:

# Get Windows host IP
export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}')
echo $WSL_GATEWAY_IP # expected something like: 172.26.32.1
                            
# Run a test container shell
docker run --rm -it --network=host busybox sh

Inside the container shell:

# Inside the container shell 
export WINDOWS_HOST_IP="172.26.32.1"  # Replace with your host IP
wget -qO- --no-check-certificate "https://$WINDOWS_HOST_IP:27124"

Firewall Issues

To temporarily disable Windows Firewall for testing (not recommended for regular use):

# Run in Admin PowerShell
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False

# Remember to re-enable after testing
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled True