Obsidian via REST

Implantação / Uso

Status de CI/CD

---

• mcp-obsidian
  • Implantação / Uso
  • Status de CI/CD
  • Ferramentas e Recursos MCP
    * Ferramentas
    * Recursos
    * Teste Rápido
  • Configurar MCP
    * Configuração Multi-URL (Recomendado)
    * Configuração de Transporte HTTP
    * Configuração Desacoplada com Autenticação
    * Configuração de Transporte Stdio
    * Configuração Legada de URL Única
    * Endpoint de Saúde
  • Configuração de Ferramentas CLI
    * Claude Code CLI
    * Gemini CLI
    * OpenCode CLI
    * Kilo Code CLI
    * Codex CLI
    * GitHub Copilot CLI
    * Referência Rápida
  • Configuração e Solução de Problemas
    * Configuração
    * Verifique se a API REST do Obsidian está em execução (Windows Host, MacOS, Linux)
    * WSL2, Docker hospedado no Ubuntu
    * Verificar Firewall do Windows
    * Desabilitar/Habilitar Firewall
    * Verificar Conectividade no Contêiner BusyBox
  • Obsidian em Docker

Ferramentas e Recursos MCP

Este servidor MCP expõe as seguintes ferramentas e recursos para assistentes de IA:

Ferramentas

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

Recursos

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

Teste Rápido

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"

Exemplo de caso de uso: "Encontre todas as ferramentas no meu cofre Obsidian para rastrear logs e métricas, faça um relatório resumido" — a IA pesquisa seu cofre, encontra notas sobre OpenTelemetry, Datadog, Prometheus, etc., e gera um resumo estruturado.

Para outras ferramentas CLI (Gemini, OpenCode, Kilo Code, Copilot), consulte o Guia de Teste Manual.

Configurar MCP

Configuração Multi-URL (Recomendado)

Use API_URLS para failover automático e auto-recuperação. O servidor testa todas as URLs em paralelo, seleciona a mais rápida e reconecta automaticamente em caso de falha.

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

Recursos de Auto-Recuperação:

• ✅ Teste paralelo de URLs na inicialização
• ✅ Seleção automática da URL mais rápida
• ✅ Monitoramento de saúde a cada 30 segundos
• ✅ Failover automático em caso de perda de conexão
• ✅ Backoff exponencial para evitar oscilações

Transportes disponíveis:

• stdio - Entrada/saída padrão (padrão, melhor para clientes MCP locais)
• http - HTTP JSON-RPC com streaming SSE (melhor para acesso remoto)

Exemplo WSL2:

Determine automaticamente o IP do gateway WSL

export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}')

Configure com múltiplas URLs de fallback

API_URLS='["https://127.0.0.1:27124", "https://'$WSL_GATEWAY_IP':27124", "https://host.docker.internal:27124"]'

Configuração de Transporte HTTP

O servidor MCP suporta transporte HTTP para acesso remoto com failover automático de URL:

{ "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" // caminho do endpoint (padrão: /mcp) } } } }

Configuração Desacoplada com Autenticação

execute o servidor MCP no docker separadamente do 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=
ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

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

Os clientes devem incluir o cabeçalho Authorization:

Authorization: Bearer your-secret-token-here

Configuração de Transporte Stdio

Para desenvolvimento local com transporte stdio (padrão):

{ "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:*" // padrão: logs desabilitados } } } }

• --rm - Remove automaticamente o contêiner e seus volumes anônimos associados ao sair
• -i, --interactive - Mantém o STDIN aberto
• -e, --env - Define variáveis de ambiente
• --name string - Atribui um nome ao contêiner
• -p, --publish - Publica a porta do contêiner no host
• Lançamentos de Pacotes NPM
• Lançamentos de Imagens Docker

Configuração Legada de URL Única

Para compatibilidade retroativa, você ainda pode usar configuração de URL única com API_HOST e 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", // URL única sem failover "API_PORT": "27124" } } } }

Nota: A configuração de URL única não fornece failover automático nem monitoramento de saúde. Use API_URLS para implantações em produção.

Endpoint de Saúde

Quando o transporte HTTP está habilitado, o servidor expõe um endpoint de verificação de saúde em /health:

curl http://localhost:3000/health

Resposta:

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

Para status de saúde abrangente, incluindo a conexão com a API do Obsidian e todos os transportes, você pode usar a função getHealthStatus() que retorna:

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

Configuração de Ferramentas CLI

Esta seção mostra como configurar ferramentas CLI populares de IA para usar o servidor MCP Obsidian.

MacOs ou Linux

curl -fsSL https://bun.sh/install | bash

Windows

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

Claude Code CLI

Docker:

Crie a configuração mcp.json

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": "", "API_URLS": "["https://host.docker.internal:27124"]" } } } } EOF

Execute o Claude com a configuração MCP

claude --mcp-config ./mcp.json

NPX/Bunx:

cat > mcp.json << 'EOF' { "mcpServers": { "obsidian": { "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "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=
-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

Transporte HTTP (servidor remoto):

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

Listar e gerenciar servidores:

gemini mcp list gemini mcp remove obsidian

OpenCode CLI

Crie opencode.json na raiz do seu projeto:

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

Transporte HTTP:

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

Kilo Code CLI

Crie .kilocode/mcp.json no seu projeto ou ~/.kilocode/cli/global/settings/mcp_settings.json globalmente:

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

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

Codex CLI

Docker:

Registre o servidor MCP

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

Crie ~/.copilot/mcp-config.json (ou .copilot/mcp-config.json na raiz do repositório):

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

Nota: O Copilot CLI v0.0.340+ requer a sintaxe ${VAR} para expansão de variáveis de ambiente. Defina OBSIDIAN_API_KEY no seu shell antes de executar.

Referência Rápida

Ferramenta CLI	Arquivo de Configuração	Suporte a Docker	Transporte HTTP
Claude Code	mcp.json	✅	✅
Gemini	settings.json	✅	✅
OpenCode	opencode.json	✅	✅
Kilo Code	.kilocode/mcp.json	✅	✅
Codex	comandos CLI	✅	✅
Copilot	~/.copilot/mcp-config.json	✅	✅

Para testes e verificação detalhados, consulte o Guia de Testes Manuais.

Configuração e Solução de Problemas

Configuração

• Execute o aplicativo Obsidian Desktop e habilite a API REST Local nas Configurações.

Essa configuração permitirá que você se conecte à API REST Local a partir de qualquer interface de rede (não apenas localhost, o que é essencial para a configuração do WSL2).

• Copie a chave de API das Configurações do Obsidian; você precisará dela para a configuração do MCP.
• Verifique se a API REST Local do Obsidian está em execução e acessível a partir da sua máquina.
• O próximo passo é sempre verificar a configuração de rede na sua máquina (regras de firewall, etc.).

Verifique se a API REST do Obsidian está em execução (Windows Host, MacOS, Linux)

Execute no terminal CMD do Windows:

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

Resposta esperada da API REST:

{ "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, Docker hospedado no Ubuntu

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

Execute dentro do terminal Ubuntu do WSL2:

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

Verifique o Firewall do Windows

Execute a GUI e configure as regras manualmente:

Windows Defender Firewall / Inbound Rules. Press Win+R and type WF.msc or firewall.cpl

WF.msc firewall.cpl # and then press 'Advanced settings'

Ou execute no Windows PowerShell como Administrador:

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

Ou execute no terminal CMD do Windows:

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

Desabilitar/Habilitar Firewall

Execute no Windows PowerShell como Administrador:

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

Verifique a Conectividade no Contêiner BusyBox

Estas etapas nos permitem confirmar que a configuração de rede está correta e que o contêiner pode se conectar à API REST Local.

Execute dentro do terminal Ubuntu do WSL2:

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

Obsidian Dockerizado

Obsidian Dockerizado