@leonardocrdso/obsidian-mcp

MCP server para integração com o Obsidian via plugin Local REST API.

Cobertura completa da API com 30 tools organizadas em 8 módulos.

Requisitos

• Obsidian com o plugin Local REST API instalado e ativo
• Node.js 18+ ou Bun

Configuração

1. Setup interativo (recomendado)

npx @leonardocrdso/obsidian-mcp --setup

  Obsidian MCP — Configuracao

  API Key: sua-api-key-aqui
  Host [127.0.0.1]: 192.168.1.50
  Porta [27124]:
  Protocolo [https]:

  Configuracao salva em ~/.obsidian-mcp.json

O setup pede cada item e salva em ~/.obsidian-mcp.json. Para reconfigurar, basta rodar --setup novamente.

2. Registrar no AI Tool

Claude Code (CLI)

claude mcp add obsidian -- npx @leonardocrdso/obsidian-mcp

Claude Code (Cowork / Headless)

Para usar com claude --cowork ou em modo headless, passe a config MCP via flag:

claude --mcp-config mcp.json

Crie o arquivo mcp.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@leonardocrdso/obsidian-mcp"]
    }
  }
}

Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@leonardocrdso/obsidian-mcp"]
    }
  }
}

Cursor

Adicione ao .cursor/mcp.json do projeto:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@leonardocrdso/obsidian-mcp"]
    }
  }
}

Windsurf

Adicione ao ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@leonardocrdso/obsidian-mcp"]
    }
  }
}

Variáveis de ambiente (alternativa)

Se preferir, configure via variáveis de ambiente em vez do setup interativo:

| Variável | Obrigatória | Padrão | Descrição | |---|---|---|---| | OBSIDIAN_API_KEY | Sim | — | API key do plugin Local REST API | | OBSIDIAN_HOST | Não | 127.0.0.1 | Host do Obsidian | | OBSIDIAN_PORT | Não | 27124 | Porta do plugin | | OBSIDIAN_PROTOCOL | Não | https | Protocolo (http ou https) |

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@leonardocrdso/obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "sua-api-key-aqui"
      }
    }
  }
}

Prioridade de configuração: arquivo ~/.obsidian-mcp.json > variáveis de ambiente.

Tools (30)

Vault (9)

| Tool | Descrição | |---|---| | vaultListFiles | Lista arquivos e pastas do vault | | vaultGetFile | Retorna conteúdo de um arquivo | | vaultGetMetadata | Retorna metadata (frontmatter, tags) | | vaultCreateFile | Cria ou substitui um arquivo | | vaultAppendContent | Adiciona conteúdo ao final | | vaultPatchContent | Insere conteúdo em local específico (suporta targetScope) | | vaultDeleteFile | Remove um arquivo | | vaultOpenFile | Abre arquivo no Obsidian | | vaultMoveFile | Move arquivo preservando histórico e links (Destination + Allow-Overwrite) |

Commands (2)

| Tool | Descrição | |---|---| | commandsList | Lista comandos disponíveis | | commandsExecute | Executa um comando |

Search (2)

| Tool | Descrição | |---|---| | searchSimple | Busca texto no vault | | searchAdvanced | Busca com Dataview DQL ou JsonLogic |

Active File (5)

| Tool | Descrição | |---|---| | activeFileGet | Retorna conteúdo do arquivo ativo | | activeFileUpdate | Substitui conteúdo do arquivo ativo | | activeFileAppend | Adiciona conteúdo ao arquivo ativo | | activeFilePatch | Insere conteúdo em local específico (suporta targetScope) | | activeFileDelete | Remove o arquivo ativo |

Periodic Notes (5)

Aceitam year/month/day opcionais para alvo em data específica (informe os três juntos ou nenhum). | Tool | Descrição | |---|---| | periodicGetNote | Retorna nota periódica (atual ou data específica) | | periodicCreateNote | Cria/substitui nota periódica | | periodicAppendContent | Adiciona conteúdo à nota periódica | | periodicPatchContent | Insere conteúdo em local específico (suporta targetScope) | | periodicDeleteNote | Remove nota periódica |

Business Rules (5)

| Tool | Descrição | |---|---| | businessRulesList | Lista regras de negócio de um projeto | | businessRulesGet | Lê o conteúdo bruto de uma regra | | businessRulesCreate | Cria nova regra com template padronizado (auto-acionada) | | businessRulesUpdate | Atualiza frontmatter ou seção de uma regra | | businessRulesArchive | Move regra para _arquivadas/ e marca status |

Project (1)

| Tool | Descrição | |---|---| | projectInit | Inicializa estrutura de projeto no vault (CLAUDE.md + Regras/, Decisões/, Notas/) — idempotente |

Tags (1)

| Tool | Descrição | |---|---| | tagsList | Lista todas as tags do vault com contagem (inline + frontmatter, prefixos hierárquicos somam) |

Desenvolvimento

git clone https://github.com/leonardocrdso/obsidian-mcp.git
cd obsidian-mcp
bun install
bun run dev --setup  # configurar
bun run dev          # iniciar servidor

License

MIT