Obsidian Claude Code

Um plugin Obsidian que integra o Claude Code aos seus cofres por meio de um servidor MCP.

Documentação

Obsidian Claude Code

Um plugin para Obsidian que implementa um servidor MCP (Model Context Protocol) para permitir a integração do Claude Code com cofres do Obsidian.

Este plugin permite que o Claude Code e outros clientes MCP (como o Claude Desktop) interajam com seu cofre do Obsidian, fornecendo assistência com IA e acesso direto às suas notas e arquivos.

Recursos

Servidor MCP de Transporte Duplo: Suporta tanto WebSocket (para Claude Code) quanto HTTP/SSE (para Claude Desktop)
Descoberta Automática: O Claude Code encontra e conecta-se automaticamente ao seu cofre
Operações de Arquivo: Leia e escreva arquivos do cofre através do protocolo MCP
Contexto do Workspace: Fornece o arquivo ativo atual e a estrutura do cofre para o Claude
Suporte a Múltiplos Clientes: Conecte tanto o Claude Code quanto o Claude Desktop simultaneamente
Portas Configuráveis: Evite conflitos ao executar vários cofres

Configuração do Cliente MCP

Este plugin atua como um servidor MCP ao qual vários clientes Claude podem se conectar. Veja como configurar diferentes clientes:

Claude Desktop (a partir de 2025-06-09)

O Claude Desktop requer uma configuração especial para conectar-se ao servidor MCP do Obsidian, pois não suporta diretamente transportes HTTP. Usaremos o mcp-remote, uma ferramenta que cria uma ponte local stdio para o endpoint HTTP do servidor.

Etapas de Configuração:

Instale e habilite este plugin no Obsidian.
Certifique-se de ter o Node.js instalado, pois o npx (que vem com o Node.js) é usado para executar a ferramenta de ponte.
Localize o arquivo de configuração do Claude Desktop:
- macOS: $HOME/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione o servidor MCP do Obsidian à sua configuração usando o comando mcp-remote. O npx baixará e executará automaticamente para você.
```
{
	"mcpServers": {
		"obsidian": {
			"command": "npx",
			"args": ["mcp-remote", "http://localhost:22360/sse"],
			"env": {}
		}
	}
}
```
Reinicie o Claude Desktop após fazer a alteração na configuração.
Teste a conexão perguntando ao Claude sobre seu cofre: "Quais arquivos estão no meu cofre do Obsidian?"

Outros Clientes MCP (com suporte direto a HTTP)

Se você estiver usando um cliente MCP que suporta diretamente o transporte legado "HTTP com SSE", pode usar uma configuração mais simples sem a ponte mcp-remote.

Exemplo de Configuração:

{
	"mcpServers": {
		"obsidian": {
			"url": "http://localhost:22360/sse",
			"env": {}
		}
	}
}

Claude Code CLI

O Claude Code descobre e conecta-se automaticamente aos cofres do Obsidian através do WebSocket.

Etapas de Uso:

Instale e habilite este plugin no Obsidian
Execute o Claude Code no seu terminal: claude
Selecione seu cofre usando o comando /ide
Escolha "Obsidian" na lista de IDEs
O Claude Code conectará automaticamente via WebSocket

Configuração de Porta

Porta Padrão: O plugin usa a porta 22360 por padrão para evitar conflitos com serviços de desenvolvimento comuns.

Configuração de Porta Personalizada:

Vá para Configurações do Obsidian → Plugins da Comunidade → Claude Code → Configurações
Altere a "Porta do Servidor HTTP" na seção de Configuração do Servidor MCP

Atualize a configuração do Claude Desktop para usar a nova porta:

{
	"mcpServers": {
		"obsidian": {
			"url": "http://localhost:22360/mcp",
			"env": {}
		}
	}
}

NOTA: Você pode alterar a porta nas configurações.

Reinicie o Claude Desktop para aplicar as alterações

Múltiplos Cofres: Se você executar vários cofres do Obsidian com este plugin, cada cofre precisa de uma porta única. O plugin detectará automaticamente conflitos de porta e o orientará a configurar portas diferentes.

Uma Nota sobre a Versão da Especificação MCP

A partir de 2025-06-09

[!IMPORTANT] Este plugin usa intencionalmente uma especificação MCP mais antiga para transporte HTTP. O mais recente "Protocolo HTTP Streamable" (2025-03-26) ainda não é suportado pela maioria dos clientes MCP, incluindo Claude Code e Claude Desktop.

Para garantir compatibilidade, usamos o legado "Protocolo HTTP com SSE" (2024-11-05). Aderir à especificação mais recente levará a falhas de conexão com as ferramentas atuais.

Solução de Problemas

Claude Desktop não conectando:

Verifique o caminho do arquivo de configuração e a sintaxe JSON
Certifique-se de que o Obsidian esteja em execução com o plugin habilitado
Verifique se a porta (22360) não está bloqueada pelo firewall
Reinicie o Claude Desktop após alterações na configuração

Claude Code não encontrando o cofre:

Verifique se o plugin está habilitado no Obsidian
Verifique se há arquivos .lock no diretório de configuração do Claude:
- $CLAUDE_CONFIG_DIR/ide/ se a variável de ambiente estiver definida
- ~/.config/claude/ide/ (padrão desde o Claude Code v1.0.30)
- ~/.claude/ide/ (localização legada)
Reinicie o Obsidian se o cofre não aparecer na lista /ide

Conflitos de porta:

Configure uma porta diferente nas configurações do plugin
Atualize as configurações do cliente para corresponder à nova porta
Portas alternativas comuns: 22361, 22362, 8080, 9090

Arquitetura de Ferramentas

Este plugin implementa um sistema de ferramentas flexível que permite que diferentes ferramentas sejam expostas a diferentes clientes MCP:

Categorias de Ferramentas

Ferramentas Compartilhadas (disponíveis tanto para IDE quanto para clientes MCP):
- Operações de arquivo: view, str_replace, create, insert
- Operações de workspace: get_current_file, get_workspace_files
- Acesso à API do Obsidian: obsidian_api
Ferramentas Específicas para IDE (disponíveis apenas via WebSocket do Claude Code):
- getDiagnostics - Diagnósticos do sistema e do cofre
- openDiff - Operações de visualização de diff (stub para Obsidian)
- close_tab - Gerenciamento de abas (stub para Obsidian)
- closeAllDiffTabs - Operações em massa de abas (stub para Obsidian)
Ferramentas Exclusivas do MCP (disponíveis apenas via HTTP/SSE):
- Atualmente nenhuma, mas a arquitetura suporta adicioná-las

Adicionando Novas Ferramentas

Para adicionar uma nova ferramenta ao plugin:

Para Ferramentas Compartilhadas (disponíveis tanto para IDE quanto para MCP):

Adicione a definição da ferramenta a src/tools/general-tools.ts no array GENERAL_TOOL_DEFINITIONS
Adicione a implementação no método createImplementations() da classe GeneralTools
A ferramenta estará automaticamente disponível para clientes WebSocket e HTTP

Para Ferramentas Específicas para IDE:

Adicione a definição da ferramenta a src/ide/ide-tools.ts no array IDE_TOOL_DEFINITIONS
Adicione a implementação no método createImplementations() da classe IdeTools
A ferramenta estará disponível apenas para o Claude Code via WebSocket

Para Ferramentas Exclusivas do MCP:

Adicione a definição da ferramenta a src/tools/mcp-only-tools.ts no array MCP_ONLY_TOOL_DEFINITIONS
Crie uma classe de implementação semelhante a GeneralTools ou IdeTools
Atualize src/mcp/dual-server.ts para registrar as ferramentas apenas no registro HTTP

Fluxo de Registro de Ferramentas

O plugin usa um sistema de registro duplo:

Registro WebSocket: Contém ferramentas compartilhadas + ferramentas específicas para IDE
Registro HTTP: Contém ferramentas compartilhadas + ferramentas exclusivas do MCP

Essa separação garante que:

O Claude Code tenha acesso à funcionalidade específica da IDE
Clientes MCP padrão vejam apenas ferramentas apropriadas
A funcionalidade compartilhada esteja disponível para todos os clientes

Desenvolvimento

Este projeto usa TypeScript para fornecer verificação de tipos e documentação. O repositório depende da API mais recente do plugin (obsidian.d.ts) no formato de Definição TypeScript, que contém comentários TSDoc descrevendo o que ela faz.

Lançando novas versões

Atualize seu manifest.json com o novo número de versão, como 1.0.1, e a versão mínima do Obsidian necessária para seu lançamento mais recente.
Atualize seu arquivo versions.json com "new-plugin-version": "minimum-obsidian-version" para que versões mais antigas do Obsidian possam baixar uma versão mais antiga do seu plugin que seja compatível.
Crie um novo lançamento no GitHub usando seu novo número de versão como a "Tag version". Use o número de versão exato, não inclua um prefixo v. Veja um exemplo aqui: https://github.com/obsidianmd/obsidian-sample-plugin/releases
Envie os arquivos manifest.json, main.js, styles.css como anexos binários. Nota: O arquivo manifest.json deve estar em dois lugares, primeiro no caminho raiz do seu repositório e também no lançamento.
Publique o lançamento.