get_note_contentLABSCO SUMMARY
Built for the vault that is not on the same host as the agent.
Three tools is a small surface, and read-only. What earns the setup is everything around the connection: parallel URL probing, fastest-wins selection, a 30-second health check and exponential backoff, plus a published container image. If Obsidian runs on Windows and your agent runs in WSL2 or Docker, that is the part that usually breaks, and this is the piece it was written for.
What it is
An MCP server that talks to the Obsidian Local REST API plugin running in the desktop app, so an agent can search your vault and pull a note's content and metadata. Its distinguishing feature is connection handling: give it several candidate URLs and it tests them in parallel, keeps the fastest, re-checks health every 30 seconds, and fails over on its own — which is what makes it survive a WSL2 gateway IP change or a Docker network restart.
What you get
- A note's content and metadata fetched by vault path —
get_note_content - Notes found by a query string, and the same query run as a semantic search —
obsidian_search,obsidian_semantic_search - Any note addressable as a resource under
obsidian://{path}, so a client can reference it without a tool call - A
/healthendpoint when HTTP transport is on, reporting transport state and whether auth is enabled
Requirements
Obsidian on the desktop with the Local REST API plugin enabled, and the key it shows you in API_KEY. API_URLS takes a JSON array or semicolon-separated list of vault URLs — that is the recommended form; API_HOST and API_PORT still work as the older single-URL config but give you no failover and no health monitoring. Run it as @oleksandrkucherenko/mcp-obsidian 1.0.3 over stdio, or as the container ghcr.io/oleksandrkucherenko/obsidian-mcp:latest. Over HTTP it binds MCP_HTTP_PORT (default 3000) at MCP_HTTP_PATH (default /mcp), and it only requires an Authorization: Bearer header when you set MCP_HTTP_TOKEN — set it before the port leaves your machine.
Setup effort
One command plus a key — claude mcp add obsidian -- bunx -y @oleksandrkucherenko/mcp-obsidian, then supply credentials
USE CASES
01
Answering a question from notes you already wrote
Search the vault for the topic, then pull the full text of the notes that came back instead of working from titles.
02
Finding a note when you cannot remember the wording
Run the query as a semantic search, which matches on meaning rather than the exact string, then open the best hit.
03
Reaching a vault that lives on another machine
List every address the vault might answer on in API_URLS — loopback, the WSL2 gateway, host.docker.internal — and let the server pick and re-pick without you editing config.
04
Serving the vault to a remote client
Switch to HTTP transport, set a bearer token, and check /health to confirm the Obsidian connection is up before pointing a client at it.
3 tools
Listed in project docs. Your client may show a different list.
obsidian_searchobsidian_semantic_searchBEFORE YOU INSTALL
What to know first
Tools you get
3 tools named in the project's documentation.
Requires
- API_KEY in your environment
- API_URLS in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
claude mcp add obsidian -- bunx -y @oleksandrkucherenko/mcp-obsidianMCP Clients
Claude Code, Kilo Code
JSON
{
"mcpServers": {
"obsidian": {
"command": "bunx",
"args": [
"-y",
"@oleksandrkucherenko/mcp-obsidian"
],
"env": {
"API_KEY": "<YOUR_API_KEY>",
"API_URLS": "[\"https://127.0.0.1:27124\"]"
}
}
}
}Gemini CLI
GEMINI CLI · TERMINAL
gemini mcp add -e API_KEY=<YOUR_API_KEY> -e API_URLS='["https://127.0.0.1:27124"]' obsidian bunx -y @oleksandrkucherenko/mcp-obsidianOpenCode
OPENCODE · JSON
{
"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
}
}
}Codex
CODEX · TERMINAL
codex mcp add obsidian --command "bunx -y @oleksandrkucherenko/mcp-obsidian" --env API_KEY=<YOUR_API_KEY> --env 'API_URLS=["https://127.0.0.1:27124"]'GitHub Copilot
GITHUB COPILOT · 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": [
"*"
]
}
}
}Windsurf — Docker
WINDSURF — DOCKER · JSON
{
"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": "<YOUR_API_KEY>",
"API_URLS": "[\"https://127.0.0.1:27124\",\"https://172.26.32.1:27124\"]",
"DEBUG": "mcp:*"
}
}
}
}
