mcpField
M
mcp-obsidian

mcp-obsidian

ローカル
github.comメモリ・ナレッジ133 日前に更新

mcp-obsidian について

mcp-obsidianは、Local REST APIを介してObsidian VaultをAIアシスタントに接続します。ノートの取得や検索を行うユーザー向けで、キーワード検索とセマンティック検索に加え、URL切り替えとstdio/HTTPトランスポートに対応します。

主な機能

  1. 01ノート本文とメタデータの取得
  2. 02クエリによるノート検索
  3. 03セマンティック検索
  4. 04複数URLの確認と自動切り替え
  5. 05stdioとHTTPトランスポートへの対応

活用シーン

  1. 01Vaultから特定のテーマに関するノートを探す
  2. 02ログや監視ツールに関するノートを要約する
  3. 03Obsidian APIの接続障害時に接続先を切り替える

MCP 対応

MCPサーバーとして、Local REST API経由でノート取得、キーワード検索、セマンティック検索のツールを公開し、obsidian:// URIでノートリソースを提供します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"oleksandrkucherenko-mcp-obsidian-via-rest": {
"command": "npx",
"args": [
"-y",
"@oleksandrkucherenko/mcp-obsidian"
],
"env": {
"API_KEY": "<API_KEY>",
"API_URLS": "<API_URLS>",
"API_HOST": "<API_HOST>",
"API_PORT": "<API_PORT>",
"MCP_TRANSPORTS": "<MCP_TRANSPORTS>",
"MCP_HTTP_PORT": "<MCP_HTTP_PORT>",
"MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
"MCP_HTTP_TOKEN": "<MCP_HTTP_TOKEN>"
}
}
}
}
起動コマンドnpx -y @oleksandrkucherenko/mcp-obsidian
設定が必要な環境変数
API_KEYシークレットObsidian Local REST API key
API_URLSJSON array or semicolon-separated list of Obsidian REST API URLs for failover
API_HOSTObsidian REST API host (legacy single-URL config)
API_PORTObsidian REST API port (legacy single-URL config)
MCP_TRANSPORTSEnabled transports (default: stdio,http)
MCP_HTTP_PORTHTTP transport bind port (default: 3000)
MCP_HTTP_HOSTHTTP transport bind host (default: 0.0.0.0)
MCP_HTTP_TOKENシークレットBearer token for HTTP transport authentication

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@oleksandrkucherenko/mcp-obsidian1.3.3
ocighcr.io/oleksandrkucherenko/obsidian-mcp:1.3.3
ocidocker.io/oleksandrkucherenko/obsidian-mcp:1.3.3

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

mcp-obsidian

Deployed / Usage

Ask DeepWiki GitHub Stars GitHub Forks NPM Downloads Docker Hub obsidian-mcp Docker Hub obsidian-vnc License: MIT

Obsidian Vault MCP server

CI/CD ステータス

NPM (npmjs.org) NPM (GitHub)

Docker (GitHub) Docker (Docker Hub)

Screenshots Cleanup


MCP ツールとリソース

この MCP サーバーは、AI アシスタントに次のツールとリソースを公開します。

ツール
ツール説明パラメーター
get_note_contentObsidian ノートの内容とメタデータを取得しますfilePath(文字列)- ノートへのパス
obsidian_searchクエリ文字列を使ってノートを検索しますquery(文字列)- 検索クエリ
obsidian_semantic_searchノートのセマンティック検索query(文字列)- 検索クエリ
リソース
リソースURI パターン説明
Obsidian ノートobsidian://{path}URI 経由でノートにアクセスします(例:obsidian://Daily/2025-01-16.md)
クイックテスト
# 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"

使用例: 「ログやメトリクスの追跡に使える、Obsidian の保管庫内のツールをすべて探して、要約レポートを作成して」 — AI が保管庫を検索し、OpenTelemetry、Datadog、Prometheus などに関するノートを見つけて、構造化された要約を生成します。

その他の CLI ツール(Gemini、OpenCode、Kilo Code、Copilot)については、手動テストガイドを参照してください。

Gemini CLI の例

MCP の設定

複数 URL の設定(推奨)

自動フェイルオーバーと自己修復には API_URLS を使用してください。 サーバーはすべての URL を並列でテストし、最速の URL を選択して、障害発生時には自動的に再接続します。

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

自己修復機能:

  • ✅ 起動時に URL を並列テスト
  • ✅ 最速の URL を自動選択
  • ✅ 30 秒ごとにヘルスを監視
  • ✅ 接続が切断された場合に自動フェイルオーバー
  • ✅ 過剰な切り替わりを防ぐ指数バックオフ

利用可能なトランスポート:

  • stdio - 標準入力/出力(デフォルト。ローカル MCP クライアントに最適)
  • http - SSE ストリーミング対応の HTTP JSON-RPC(リモートアクセスに最適)

WSL2 の例:

# 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 トランスポートの設定

MCP サーバーは、自動 URL フェイルオーバーに対応したリモートアクセス用 HTTP トランスポートをサポートしています。

{
  "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 ヘッダーを含める必要があります。

Authorization: Bearer your-secret-token-here
Stdio トランスポートの設定

stdio トランスポートを使用したローカル開発の場合(デフォルト):

{
  "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 - 終了時にコンテナと関連する匿名ボリュームを自動的に削除します

  • -i, --interactive - STDIN を開いたままにします

  • -e, --env - 環境変数を設定します

  • --name string - コンテナに名前を割り当てます

  • -p, --publish - コンテナのポートをホストに公開します

  • NPM パッケージのリリース

  • Docker イメージのリリース

従来の単一 URL 設定

後方互換性のため、API_HOST と API_PORT を使用した単一 URL 設定も引き続き利用できます。

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

注意: 単一 URL 設定では、自動フェイルオーバーやヘルス監視は利用できません。本番環境へのデプロイでは API_URLS を使用してください。

ヘルスエンドポイント

HTTP トランスポートが有効な場合、サーバーは /health にヘルスチェック用エンドポイントを公開します。

curl http://localhost:3000/health

レスポンス:

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

Obsidian API 接続とすべてのトランスポートを含む包括的なヘルスステータスを確認するには、次の値を返す getHealthStatus() 関数を使用できます。

{
  "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 ツールの設定

このセクションでは、一般的な AI CLI ツールを MCP Obsidian サーバーで使用するための設定方法を説明します。

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

NPX/Bunx:

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 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 \
  bunx -y @oleksandrkucherenko/mcp-obsidian

HTTP トランスポート(リモートサーバー):

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

サーバーの一覧表示と管理:

gemini mcp list
gemini mcp remove obsidian
OpenCode CLI

プロジェクトのルートに opencode.json を作成します。

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 トランスポート:

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

プロジェクト内に .kilocode/mcp.json を作成するか、グローバル設定として ~/.kilocode/cli/global/settings/mcp_settings.json を作成します。

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

HTTP トランスポート:

{
  "mcpServers": {
    "obsidian-http": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
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=<your-obsidian-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=<your-obsidian-api-key> \
  --env 'API_URLS=["https://127.0.0.1:27124"]'
GitHub Copilot CLI

~/.copilot/mcp-config.json(またはリポジトリのルートに .copilot/mcp-config.json)を作成します。

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

注意: Copilot CLI v0.0.340 以降では、環境変数の展開に ${VAR} 構文が必要です。実行前にシェルで OBSIDIAN_API_KEY を設定してください。

クイックリファレンス
CLI ツール設定ファイルDocker 対応HTTP トランスポート
Claude Codemcp.json✅✅
Geminisettings.json✅✅
OpenCodeopencode.json✅✅
Kilo Code.kilocode/mcp.json✅✅
CodexCLI コマンド✅✅
Copilot~/.copilot/mcp-config.json✅✅

詳細なテストと検証については、手動テストガイドを参照してください。

セットアップとトラブルシューティング

セットアップ

Obsidian Local REST API のセットアップ

この設定により、任意のネットワークインターフェースから Local REST API に接続できるようになります(localhost のみではなく、WSL2 のセットアップではこれが重要です)。

  • Obsidian の設定から API キーをコピーします。MCP の設定に必要になります。

  • Obsidian Local REST API が実行中であり、お使いのマシンからアクセスできることを確認します。

  • 次に、お使いのマシンのネットワーク設定(ファイアウォールルールなど)を必ず確認してください。

Obsidian REST API が実行中であることを確認する(Windows ホスト、MacOS、Linux)

Windows CMD ターミナルで実行します:

# 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

REST API の期待される応答:

{
  "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
}
WSL2、Ubuntu 上でホストされた Docker
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

WSL2 の Ubuntu ターミナル内で実行します:

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 ファイアウォールを確認する

GUI を起動し、ルールを手動で設定します:

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

または、管理者として Windows PowerShell で実行します:

# 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

または、Windows CMD ターミナルで実行します:

# 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
ファイアウォールを無効化/有効化する

管理者として Windows PowerShell で実行します:

# 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
BusyBox コンテナの接続を確認する

これらの手順により、ネットワーク設定が正しく、コンテナが Local REST API に接続できることを確認できます。

WSL2 の Ubuntu ターミナル内で実行します:

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

Docker 化された Obsidian

Docker 化された Obsidian

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。