# Mcp Obsidian Via Rest

> MCP Server connected to Obsidian Vault with Local REST API. (re-write it completely with BUN to make it faster and more lightweight)

- **Type:** MCP server
- **Install:** `agentstack add mcp-oleksandrkucherenko-mcp-obsidian-via-rest`
- **Verified:** Pending review
- **Seller:** [OleksandrKucherenko](https://agentstack.voostack.com/s/oleksandrkucherenko)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 1.0.3
- **License:** MIT
- **Upstream author:** [OleksandrKucherenko](https://github.com/OleksandrKucherenko)
- **Source:** https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest
- **Website:** http://mcp-obsidian.artfulbits.se/

## Install

```sh
agentstack add mcp-oleksandrkucherenko-mcp-obsidian-via-rest
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
# 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/04_manual_testing.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.

```jsonc
{
  "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:**

```bash
# 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:

```jsonc
{
  "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

```bash
# 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
```

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

Clients must include the Authorization header:

```http
Authorization: Bearer your-secret-token-here
```

### Stdio Transport Configuration

For local development with stdio transport (default):

```jsonc
{
  "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](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/pkgs/npm/mcp-obsidian)
- [Docker Image Releases](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/pkgs/container/obsidian-mcp)

### Legacy Single-URL Configuration

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

```jsonc
{
  "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`:

```bash
curl http://localhost:3000/health
```

**Response:**

```json
{
  "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:

```json
{
  "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.

```bash
# MacOs or Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"
```

### Claude Code CLI

**Docker:**
```bash
# 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:**
```bash
cat > mcp.json ",
        "API_URLS": "[\"https://127.0.0.1:27124\"]"
      }
    }
  }
}
EOF

claude --mcp-config ./mcp.json
```

### Gemini CLI

**Docker:**
```bash
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:**
```bash
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):**
```bash
gemini mcp add --transport http obsidian-http http://localhost:3000/mcp
```

**List and manage servers:**
```bash
gemini mcp list
gemini mcp remove obsidian
```

### OpenCode CLI

Create `opencode.json` in your project root:

**Docker:**
```jsonc
{
  "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:**
```jsonc
{
  "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:**
```jsonc
{
  "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:**
```json
{
  "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:**
```json
{
  "mcpServers": {
    "obsidian": {
      "command": "bunx",
      "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"],
      "env": {
        "API_KEY": "",
        "API_URLS": "[\"https://127.0.0.1:27124\"]"
      }
    }
  }
}
```

**HTTP Transport:**
```json
{
  "mcpServers": {
    "obsidian-http": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}
```

### Codex CLI

**Docker:**
```bash
# 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:**
```bash
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:**
```json
{
  "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:**
```json
{
  "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/04_manual_testing.md).

## Setup and Troubleshooting

### Setup

- Run [Obsidian Desktop Application](https://obsidian.md/) 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](https://github.com/OleksandrKucherenko)
- **Source:** [OleksandrKucherenko/mcp-obsidian-via-rest](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest)
- **License:** MIT
- **Homepage:** http://mcp-obsidian.artfulbits.se/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v1.0.3 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **1.0.3** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-oleksandrkucherenko-mcp-obsidian-via-rest
- Seller: https://agentstack.voostack.com/s/oleksandrkucherenko
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.