Mcp Obsidian Via Rest

mcp-obsidian

Deployed / Usage

[](https://deepwiki.com/OleksandrKucherenko/mcp-obsidian-via-rest) [](https://www.npmjs.com/package/@oleksandrkucherenko/mcp-obsidian) [](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/stargazers) [](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/network/members) [](https://www.npmjs.com/package/@oleksandrkucherenko/mcp-obsidian) [](https://hub.docker.com/r/oleksandrkucherenko/obsidian-mcp) [](https://hub.docker.com/r/oleksandrkucherenko/obsidian-vnc) [](LICENSE)

CI/CD Status

[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-npmjs.yml) [](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-github.yml)

[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-github.yml) [](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-hub.yml)

[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/screenshots.yml) [](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/cleanup.yaml)

---

• [mcp-obsidian](#mcp-obsidian)
• [Deployed / Usage](#deployed--usage)
• [CI/CD Status](#cicd-status)
• [MCP Tools \& Resources](#mcp-tools--resources)
• [Tools](#tools)
• [Resources](#resources)
• [Quick Test](#quick-test)
• [Configure MCP](#configure-mcp)
• [Multi-URL Configuration (Recommended)](#multi-url-configuration-recommended)
• [HTTP Transport Configuration](#http-transport-configuration)
• [Decoupled Configuration with Authentication](#decoupled-configuration-with-authentication)
• [Stdio Transport Configuration](#stdio-transport-configuration)
• [Legacy Single-URL Configuration](#legacy-single-url-configuration)
• [Health Endpoint](#health-endpoint)
• [CLI Tools Configuration](#cli-tools-configuration)
• [Claude Code CLI](#claude-code-cli)
• [Gemini CLI](#gemini-cli)
• [OpenCode CLI](#opencode-cli)
• [Kilo Code CLI](#kilo-code-cli)
• [Codex CLI](#codex-cli)
• [GitHub Copilot CLI](#github-copilot-cli)
• [Quick Reference](#quick-reference)
• [Setup and Troubleshooting](#setup-and-troubleshooting)
• [Setup](#setup)
• [Verify that the Obsidian REST API is running (Windows Host, MacOS, Linux)](#verify-that-the-obsidian-rest-api-is-running-windows-host-macos-linux)
• [WSL2, Docker hosted on Ubuntu](#wsl2-docker-hosted-on-ubuntu)
• [Verify Windows Firewall](#verify-windows-firewall)
• [Disable/Enable Firewall](#disableenable-firewall)
• [Verify Connectivity on BusyBox Container](#verify-connectivity-on-busybox-container)
• [Dockerized Obsidian](#dockerized-obsidian)

MCP Tools & Resources

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

Tools

| Tool | Description | Parameters | | -------------------------- | ------------------------------------------------- | -------------------------------------- | | get_note_content | Retrieve content and metadata of an Obsidian note | filePath (string) - Path to the note | | obsidian_search | Search notes using a query string | query (string) - Search query | | obsidian_semantic_search | Semantic search for notes | query (string) - Search query |

Resources

| Resource | URI Pattern | Description | | ------------- | ------------------- | ------------------------------------------------------------- | | Obsidian Note | obsidian://{path} | Access notes via URI (e.g., obsidian://Daily/2025-01-16.md) |

Quick Test

# 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), see [Manual Testing Guide](./docs/04manualtesting.md#quick-test-commands).

Configure MCP

Multi-URL Configuration (Recommended)

Use API_URLS for automatic failover and self-healing. The server tests all URLs in parallel, selects the fastest one, and automatically reconnects on failure.

{
  "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": "",
        // 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:*"
      }
    }
  }
}

Self-Healing Features:

• ✅ Parallel URL testing on startup
• ✅ Automatic selection of fastest URL
• ✅ Health monitoring every 30 seconds
• ✅ Automatic failover on connection loss
• ✅ Exponential backoff to prevent thrashing

Available transports:

• stdio - Standard input/output (default, best for local MCP clients)
• http - HTTP JSON-RPC with SSE streaming (best for remote access)

WSL2 Example:

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

HTTP Transport Configuration

The MCP server supports HTTP transport for remote access with automatic URL failover:

{
  "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": "",
        "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)
      }
    }
  }
}

Decoupled Configuration with Authentication

# 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="" \
  -e API_URLS="${API_URLS}" \
  -e MCP_HTTP_TOKEN= \
  ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

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

Clients must include the Authorization header:

Authorization: Bearer your-secret-token-here

Stdio Transport Configuration

For local development with stdio transport (default):

{
  "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": "",
        "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

Legacy Single-URL Configuration

For backward compatibility, you can still use single-URL configuration with API_HOST and API_PORT:

{
  "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": "",
        "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. Use API_URLS for production deployments.

Health Endpoint

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

curl http://localhost:3000/health

Response:

{
  "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 the getHealthStatus() 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
}

CLI Tools Configuration

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"

Claude Code CLI

Docker:

# Create mcp.json configuration
cat > mcp.json ",
        "API_URLS": "[\"https://host.docker.internal:27124\"]"
      }
    }
  }
}
EOF

# Run Claude with MCP config
claude --mcp-config ./mcp.json

NPX/Bunx:

cat > mcp.json ",
        "API_URLS": "[\"https://127.0.0.1:27124\"]"
      }
    }
  }
}
EOF

claude --mcp-config ./mcp.json

Gemini CLI

Docker:

gemini mcp add \
  -e 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= \
  -e API_URLS='["https://127.0.0.1:27124"]' \
  obsidian \
  bunx -y @oleksandrkucherenko/mcp-obsidian

HTTP Transport (remote server):

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

List and manage servers:

gemini mcp list
gemini mcp remove obsidian

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": ["bunx", "-y", "@oleksandrkucherenko/mcp-obsidian"],
      "environment": {
        "API_KEY": "{env:API_KEY}",
        "API_URLS": "[\"https://127.0.0.1:27124\"]"
      },
      "enabled": true
    }
  }
}

HTTP Transport:

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

Kilo Code CLI

Create .kilocode/mcp.json in your project or ~/.kilocode/cli/global/settings/mcp_settings.json globally:

Docker:

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

NPX/Bunx:

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

HTTP Transport:

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

Codex CLI

Docker:

# 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= \
  --env 'API_URLS=["https://host.docker.internal:27124"]'

NPX/Bunx:

codex mcp add obsidian \
  --command "bunx -y @oleksandrkucherenko/mcp-obsidian" \
  --env 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": "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. Set OBSIDIAN_API_KEY in your shell before running.

Quick Reference

| CLI Tool | Config File | Docker Support | HTTP Transport | | ----------- | ---------------------------- | -------------- | -------------- | | Claude Code | mcp.json | ✅ | ✅ | | Gemini | settings.json | ✅ | ✅ | | OpenCode | opencode.json | ✅ | ✅ | | Kilo Code | .kilocode/mcp.json | ✅ | ✅ | | Codex | CLI commands | ✅ | ✅ | | Copilot | ~/.copilot/mcp-config.json | ✅ | ✅ |

For detailed testing and verification, see [Manual Testing Guide](./docs/04manualtesting.md).

Setup and Troubleshooting

Setup

• Run Obsidian Desktop Application and enable [Local REST API](https://github.com/coddingtonbear/obsidian-local-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OleksandrKucherenko
• Source: OleksandrKucherenko/mcp-obsidian-via-rest
• License: MIT
• Homepage: http://mcp-obsidian.artfulbits.se/

Install and usage instructions live in the source repository linked above.