Labsco
OleksandrKucherenko logo

Obsidian via REST

★ 13

from OleksandrKucherenko

Access and manage your Obsidian vault through a local REST API.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#devops#git#monitoring

mcp-obsidian

CI/CD Status

MCP Tools & Resources

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

Tools

ToolDescriptionParameters
get_note_contentRetrieve content and metadata of an Obsidian notefilePath (string) - Path to the note
obsidian_searchSearch notes using a query stringquery (string) - Search query
obsidian_semantic_searchSemantic search for notesquery (string) - Search query

Resources

ResourceURI PatternDescription
Obsidian Noteobsidian://{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.

Gemini CLI Example

Configure MCP

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

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

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

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

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": "<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. 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
}

Dockerized Obsidian

Obsidian Dockerized