Obsidian MCP Server - Enhanced

Fornece acesso abrangente a um cofre do Obsidian, permitindo que agentes de IA leiam, escrevam, pesquisem e gerenciem notas por meio do plugin Local REST API.

GitHub

Experimente este MCPPatrocinado

Documentação

Obsidian MCP Server - Enhanced

Servidor MCP Obsidian Aprimorado com Integração Remota Claude.ai, Suporte Tailscale e Capacidades Avançadas de Consulta!

🔥 Aviso de Fork Aprimorado: Esta é uma versão aprimorada do excelente cyanheads/obsidian-mcp-server com recursos adicionais especificamente adaptados para integração remota com Claude.ai, consulta avançada de tarefas e segurança via Tailscale.

Um servidor MCP (Model Context Protocol) que fornece acesso abrangente ao seu cofre Obsidian. Permite que LLMs e agentes de IA leiam, escrevam, pesquisem e gerenciem suas notas e arquivos através do plugin Obsidian Local REST API.

Construído sobre o cyanheads/mcp-ts-template, este servidor segue uma arquitetura modular com tratamento robusto de erros, registro de logs e recursos de segurança.

🚀 Recursos Aprimorados (Este Fork)

🏛️ Suporte a Múltiplos Cofres

Acesso simultâneo a múltiplos cofres Obsidian através de um único servidor MCP:

Gerenciamento de Múltiplos Cofres: Conecte-se a múltiplas instâncias Obsidian em portas diferentes simultaneamente
Roteamento Específico por Cofre: As ferramentas roteiam automaticamente para o cofre correto com base no parâmetro vault
Autenticação Individual: Chaves de API separadas para cada cofre com autenticação MCP centralizada
Compatível com Versões Anteriores: Configurações existentes de cofre único continuam funcionando sem alterações
Configuração Dinâmica: Configuração de cofre baseada em JSON com validação e tratamento de erros

🌐 Integração Remota com Claude.ai

Integração perfeita com o recurso MCP Remoto do Claude.ai:

Modo HTTP Sem Estado: Transporte sem estado dedicado para compatibilidade com Claude.ai (MCP_HTTP_STATELESS=true)
Modo Baseado em Sessão: Gerenciamento tradicional de sessões para outros clientes MCP
Autenticação Simplificada: Usa MCP_AUTH_KEY dedicada para acesso ao servidor
Configuração Zero: Funciona imediatamente com servidores MCP Remotos do Claude.ai
Pronto para Produção: Estabilidade e tratamento de erros de nível empresarial

🔒 Acesso Remoto Seguro via Tailscale

Acesse seu cofre Obsidian com segurança de qualquer lugar:

Integração com Tailscale Funnel: Endpoints HTTPS seguros com certificados automáticos
Criptografia de Ponta a Ponta: Todo o tráfego criptografado através da rede Tailscale
Sem Encaminhamento de Portas: Nenhuma configuração de rede necessária
Controle de Acesso: Suporte integrado a ACL do Tailscale para segurança empresarial

📊 Sistema Aprimorado de Tarefas e Consultas

Capacidades avançadas de consulta além do original:

Integração com o Plugin Tasks: Integração profunda com o plugin Obsidian Tasks
Análise Avançada de Datas: Reconhecimento de datas em linguagem natural
Detecção de Prioridade: Análise de prioridade visual e baseada em texto
Múltiplos Formatos de Saída: Visualizações em tabela, lista e resumo

🔧 Monitoramento de Produção e Confiabilidade

Capacidades de monitoramento e reinicialização automática de nível empresarial:

Script de Verificação de Saúde: Validação abrangente de componentes (scripts/health-check.sh)
Monitoramento Inteligente: Reinicialização automática com gerenciamento do ciclo de vida do processo (scripts/monitor-mcp.sh)
Início Automático no macOS: Configuração de agente de inicialização para o início do sistema (scripts/setup-autostart.sh)
Gerenciamento Dinâmico de Portas: Resolução automática de conflitos de porta (intervalo 3010-3013)
Registro Aprimorado: Depuração detalhada de conexões e validação de chaves de API

🚀 Capacidades Principais: Ferramentas Obsidian 🛠️

Este servidor equipa sua IA com ferramentas especializadas para interagir com seu cofre Obsidian:

Nome da Ferramenta	Descrição	Recursos Principais
`obsidian_read_file`	Recupera o conteúdo e os metadados de um arquivo especificado.	- Leitura em formato `markdown` ou `json`. - Fallback de caminho sem diferenciar maiúsculas/minúsculas. - Inclui estatísticas do arquivo (tempo de criação/modificação).
`obsidian_update_file`	Modifica notas usando operações de arquivo inteiro.	- Conteúdo `append`, `prepend` ou `overwrite`. - Pode criar arquivos se não existirem. - Direciona arquivos por caminho, nota ativa ou nota periódica.
`obsidian_search_replace`	Executa operações de busca e substituição dentro de uma nota alvo.	- Suporta busca por string ou regex. - Opções para diferenciar maiúsculas/minúsculas, palavra inteira e substituir todas as ocorrências.
`obsidian_global_search`	Executa uma busca em todo o cofre.	- Busca por texto ou regex. - Filtro por caminho e data de modificação. - Resultados paginados.
`obsidian_list_files`	Lista arquivos e subdiretórios dentro de uma pasta especificada do cofre.	- Filtro por extensão de arquivo ou regex de nome. - Fornece uma visualização em árvore formatada do diretório.
`obsidian_manage_frontmatter`	Gerencia atomicamente o frontmatter YAML de uma nota.	- Chaves de frontmatter `get`, `set` ou `delete`. - Evita reescrever o arquivo inteiro para alterações de metadados.
`obsidian_manage_tags`	Adiciona, remove ou lista tags para uma nota.	- Gerencia tags tanto no frontmatter YAML quanto no conteúdo inline.
`obsidian_delete_file`	Exclui permanentemente um arquivo especificado do cofre.	- Fallback de caminho sem diferenciar maiúsculas/minúsculas por segurança.
`obsidian_dataview_query`	Execute consultas DQL do Dataview no seu cofre.	- Execute consultas TABLE, LIST usando sintaxe Dataview. - Consulte notas por tags, frontmatter, datas. - Gere relatórios e análises.
`obsidian_task_query`	Pesquise e analise tarefas em todo o seu cofre.	- Filtre por status, intervalos de datas, prioridades. - Múltiplos formatos de saída. - Extraia metadados de tarefas (datas de vencimento, tags).

Índice

Visão Geral

O Servidor MCP Obsidian atua como uma ponte, permitindo que aplicações (Clientes MCP) que entendem o Model Context Protocol (MCP) – como assistentes de IA avançados (LLMs), extensões de IDE ou scripts personalizados – interajam direta e seguramente com seu cofre Obsidian.

Em vez de scripts complexos ou interação manual, suas ferramentas podem aproveitar este servidor para:

Automatizar o gerenciamento do cofre: Ler notas, atualizar conteúdo, gerenciar frontmatter e tags, pesquisar arquivos, listar diretórios e excluir arquivos programaticamente.
Integrar o Obsidian em fluxos de trabalho de IA: Permitir que LLMs acessem e modifiquem sua base de conhecimento como parte de suas tarefas de pesquisa, escrita ou codificação.
Criar ferramentas Obsidian personalizadas: Criar aplicações externas que interagem com os dados do seu cofre de maneiras inovadoras.

Construído sobre o robusto mcp-ts-template, este servidor fornece uma maneira padronizada, segura e eficiente de expor a funcionalidade do Obsidian através do padrão MCP. Ele consegue isso comunicando-se com o poderoso plugin Obsidian Local REST API executando dentro do seu cofre.

Nota do Desenvolvedor: Este repositório inclui um arquivo .clinerules que serve como uma folha de referência para seu agente de codificação LLM, com referência rápida para padrões do código, localizações de arquivos e trechos de código.

Recursos

Utilitários Principais

Aproveita os utilitários robustos fornecidos pelo mcp-ts-template:

Registro de Logs: Registro estruturado e configurável (rotação de arquivos, console, notificações MCP) com redação de dados sensíveis.
Tratamento de Erros: Processamento centralizado de erros, tipos de erro padronizados (McpError) e registro automático.
Configuração: Carregamento de variáveis de ambiente (dotenv) com validação abrangente.
Validação/Sanitização de Entrada: Usa zod para validação de esquema e lógica personalizada de sanitização.
Contexto de Requisição: Rastreamento e correlação de operações via IDs de requisição únicos.
Segurança de Tipos: Tipagem forte imposta por TypeScript e esquemas Zod.
Opção de Transporte HTTP: Servidor HTTP nativo do Node.js com gerenciamento de sessão, suporte a CORS e autenticação por chave de API.

Integração com Obsidian

Integração com a API REST Local do Obsidian: Comunica-se diretamente com o plugin Obsidian Local REST API via requisições HTTP gerenciadas pelo ObsidianRestApiService.
Cobertura Abrangente de Comandos: Expõe operações-chave do cofre como ferramentas MCP (veja a seção Ferramentas).
Interação com o Cofre: Suporta leitura, atualização (anexar, prefixar, sobrescrever), pesquisa (texto/regex global, busca/substituição), listagem, exclusão e gerenciamento de frontmatter e tags.
Flexibilidade de Direcionamento: As ferramentas podem direcionar arquivos por caminho, o arquivo atualmente ativo no Obsidian ou notas periódicas (diárias, semanais, etc.).
Serviço de Cache do Cofre: Um cache inteligente em memória que melhora o desempenho e a resiliência. Ele armazena em cache o conteúdo do cofre, fornece um fallback para a ferramenta de pesquisa global se a API ao vivo falhar e atualiza periodicamente para permanecer sincronizado.
Recursos de Segurança: Fallbacks de caminho sem diferenciar maiúsculas/minúsculas para operações de arquivo, distinção clara entre tipos de modificação (anexar, sobrescrever, etc.).

Instalação

Pré-requisitos

Obsidian: Você precisa ter o Obsidian instalado.
Plugin Obsidian Local REST API: Instale e habilite o plugin Obsidian Local REST API dentro do seu cofre Obsidian.
Chave de API: Configure uma chave de API nas configurações do plugin Local REST API no Obsidian. Você precisará desta chave para configurar o servidor.
Node.js e npm: Certifique-se de ter Node.js (v18 ou posterior recomendado) e npm instalados.
Tailscale (para acesso remoto): Instale o Tailscale e habilite o Tailscale Funnel para integração remota segura com Claude.ai.

💡 Configuração Rápida: Para inicialização automática no boot, consulte o Guia de Configuração de Início Automático após a instalação.

Instalação

Clone este repositório aprimorado:

git clone https://github.com/BoweyLou/obsidian-mcp-server-enhanced.git
cd obsidian-mcp-server-enhanced

Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```
Isso compila o código TypeScript para JavaScript no diretório dist/ e torna o ponto de entrada executável.

Configuração

Variáveis de Ambiente

Configure o servidor usando variáveis de ambiente.

Essas variáveis devem ser definidas na configuração do cliente MCP (por exemplo, cline_mcp_settings.json) ou no seu ambiente antes de iniciar o servidor (se executado diretamente). Se executado diretamente, eles podem ser definidos em um arquivo .env na raiz do projeto ou diretamente no seu ambiente.

Variável	Descrição	Obrigatório	Padrão
`MCP_AUTH_KEY`	Chave de autenticação para acesso remoto ao MCP via Claude.ai. Gere com `openssl rand -hex 32`	Sim (Remoto)	`undefined`
`OBSIDIAN_VAULTS`	Matriz JSON de configurações de vault para o modo multi-vault.	Sim (Multi)	`undefined`
`OBSIDIAN_API_KEY`	Chave de API do plugin Obsidian (somente modo single-vault).	Sim (Single)	`undefined`
`OBSIDIAN_BASE_URL`	URL base da API do Obsidian (somente modo single-vault).	Sim (Single)	`http://127.0.0.1:27123`
`MCP_TRANSPORT_TYPE`	Transporte do servidor: `stdio` ou `http`.	Não	`http`
`MCP_HTTP_PORT`	Porta para o servidor HTTP.	Não	`3010`
`MCP_HTTP_HOST`	Host para o servidor HTTP.	Não	`127.0.0.1`
`MCP_HTTP_STATELESS`	Ativa o modo stateless para compatibilidade com Claude.ai.	Não	`false`
`MCP_ALLOWED_ORIGINS`	Origens separadas por vírgula para CORS. Defina para produção.	Não	(nenhum)
`CHATGPT_LAYER_ENABLED`	Defina como `true` para servir o manifesto do ChatGPT e o endpoint de ações JSON.	Não	`false`
`CHATGPT_MANIFEST_PATH`	Caminho HTTP que expõe o manifesto JSON do ChatGPT.	Não	`/.well-known/obsidian-chatgpt-manifest.json`
`CHATGPT_ACTIONS_PATH`	Caminho HTTP para ações JSON do ChatGPT (POST).	Não	`/chatgpt/actions`
`CHATGPT_FACADE_TOKEN_TTL_SECONDS`	Tempo de vida do token de acesso da fachada do ChatGPT.	Não	`3600`
`CHATGPT_FACADE_REFRESH_TOKEN_TTL_SECONDS`	Tempo de vida do token de atualização da fachada do ChatGPT.	Não	`2592000`
`CHATGPT_FACADE_SCOPES`	Escopos da fachada do ChatGPT separados por vírgula. Adicione escopos de escrita apenas para clientes explicitamente confiáveis.	Não	`obsidian:read`
`MCP_LOG_LEVEL`	Nível de registro (`debug`, `info`, `error`, etc.).	Não	`info`
`OBSIDIAN_VERIFY_SSL`	Defina como `false` para desabilitar a verificação SSL.	Não	`true`
`OBSIDIAN_ENABLE_CACHE`	Defina como `true` para habilitar o cache de vault em memória.	Não	`true`
`OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN`	Intervalo de atualização do cache de vault em minutos.	Não	`10`

Configuração Multi-Vault

O servidor suporta modos single-vault (compatível com versões anteriores) e multi-vault:

Modo Single-Vault (Legado)

# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_API_KEY=your-obsidian-plugin-api-key
OBSIDIAN_BASE_URL=http://127.0.0.1:27123
MCP_TRANSPORT_TYPE=http
MCP_HTTP_STATELESS=true

Modo Multi-Vault (Recomendado)

# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_VAULTS='[
  {
    "id": "work",
    "name": "Work Vault", 
    "apiKey": "work-vault-api-key",
    "baseUrl": "http://127.0.0.1:27123",
    "verifySsl": false
  },
  {
    "id": "personal",
    "name": "Personal Vault",
    "apiKey": "personal-vault-api-key", 
    "baseUrl": "http://127.0.0.1:27122",
    "verifySsl": false
  }
]'
MCP_TRANSPORT_TYPE=http
MCP_HTTP_STATELESS=true

Processo de Configuração

Gerar Chave de Autenticação MCP: openssl rand -hex 32
Configurar Múltiplas Instâncias do Obsidian: Instale o plugin Local REST API em portas diferentes
Obter Chaves de API: Extraia as chaves de API das configurações do plugin em cada instância do Obsidian
Configurar Vaults: Atualize .env com a configuração JSON OBSIDIAN_VAULTS
Iniciar o Servidor: npm run start:http
Acessar via Claude.ai: Use sua URL do Tailscale com MCP_AUTH_KEY

Conectando à API do Obsidian

Modo Single-Vault

Para conectar no modo single-vault, configure a URL base (OBSIDIAN_BASE_URL) e a chave de API (OBSIDIAN_API_KEY). O plugin Obsidian Local REST API oferece dois tipos de conexão:

Criptografada (HTTPS):
- Usa o endpoint seguro https:// (ex.: https://127.0.0.1:27124)
- Requer OBSIDIAN_VERIFY_SSL=false para certificados autoassinados
Não criptografada (HTTP) - Recomendada:
- Usa o endpoint http:// (ex.: http://127.0.0.1:27123)
- Configuração mais simples, sem necessidade de verificação SSL

Modo Multi-Vault

Para o modo multi-vault, configure cada vault individualmente na matriz JSON OBSIDIAN_VAULTS com sua própria chave de API e URL base. Cada vault pode usar HTTP ou HTTPS conforme necessário.

Exemplos de configuração:

Single-vault com HTTP:

"env": {
  "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
  "OBSIDIAN_API_KEY": "your-obsidian-api-key",
  "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
}

Configuração multi-vault:

"env": {
  "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
  "OBSIDIAN_VAULTS": "[{\"id\":\"work\",\"name\":\"Work\",\"apiKey\":\"work-key\",\"baseUrl\":\"http://127.0.0.1:27123\"},{\"id\":\"personal\",\"name\":\"Personal\",\"apiKey\":\"personal-key\",\"baseUrl\":\"http://127.0.0.1:27122\"}]"
}

Configurações Locais do Cliente MCP (Opcional)

Nota: Para integração remota com Claude.ai MCP, pule esta seção e use a Configuração de Acesso Remoto via Tailscale.

Para clientes MCP locais (ex.: Cline), adicione às suas configurações (ex.: cline_mcp_settings.json):

Configuração single-vault:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server-enhanced/dist/index.js"],
      "env": {
        "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
        "OBSIDIAN_API_KEY": "your-obsidian-api-key",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

Configuração multi-vault:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server-enhanced/dist/index.js"],
      "env": {
        "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
        "OBSIDIAN_VAULTS": "[{\"id\":\"work\",\"name\":\"Work Vault\",\"apiKey\":\"work-api-key\",\"baseUrl\":\"http://127.0.0.1:27123\"},{\"id\":\"personal\",\"name\":\"Personal Vault\",\"apiKey\":\"personal-api-key\",\"baseUrl\":\"http://127.0.0.1:27122\"}]",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

🌐 Configuração de Acesso Remoto (Tailscale)

Para acesso remoto ao seu vault do Obsidian de qualquer lugar, você pode usar o Tailscale para expor seu servidor MCP com segurança pela internet.

Pré-requisitos

Conta Tailscale: Cadastre-se em tailscale.com
Tailscale Instalado: Instale o Tailscale na máquina que executa o servidor MCP
Tailscale Funnel Habilitado: Ative o Tailscale Funnel para sua conta

Etapas de Configuração

Gerar Chave de Autenticação MCP:
```
openssl rand -hex 32
```

Configurar Ambiente: Configure seu arquivo .env com a chave gerada:

MCP_AUTH_KEY=your-generated-auth-key
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_HTTP_STATELESS=true

Configurar Vaults: Configure a configuração single ou multi-vault (veja Configuração Multi-Vault)
Iniciar o Servidor MCP:
```
npm run build && npm run start:http
```
Habilitar Tailscale Funnel:
```
tailscale funnel 3010
```
Obter Sua URL Pública: Verifique a URL do seu dispositivo Tailscale:
```
tailscale status --self | grep "Funnel on"
```

Configuração Remota do MCP no Claude.ai

Adicione aos seus servidores MCP remotos do Claude.ai usando sua chave de autenticação MCP:

Configuração single-vault:

{
  "url": "https://your-device.your-tailnet.ts.net/mcp?api_key=your-mcp-auth-key",
  "name": "Obsidian Vault"
}

Configuração multi-vault:

{
  "url": "https://your-device.your-tailnet.ts.net/mcp?api_key=your-mcp-auth-key",
  "name": "Obsidian Multi-Vault"
}

Nota de Autenticação: O MCP remoto do Claude.ai usa o MCP_AUTH_KEY para autenticação do servidor. As operações individuais de vault usam as chaves de API específicas do vault configuradas no seu ambiente.

Considerações de Segurança

Autenticação Dupla: Autenticação do servidor MCP via MCP_AUTH_KEY, autenticação do vault via chaves de API individuais
Criptografia Tailscale: Todo o tráfego é criptografado de ponta a ponta pelo Tailscale
Rede Privada: Somente você pode acessar o servidor através da sua rede Tailscale
SSL Automático: O Tailscale Funnel fornece certificados HTTPS automáticos
Isolamento de Vault: Cada vault usa sua própria chave de API para controle de acesso seguro

Exemplo de Uso

Após a configuração, você pode usar as ferramentas remotamente pelo Claude.ai:

Comandos single-vault (usa o vault padrão):

Use obsidian_task_query to show me tasks due today with format="table"

Comandos multi-vault (especifique o vault):

Use obsidian_task_query with vault="work" to show me work tasks due today

Use obsidian_read_file with filePath="daily-note.md" and vault="personal"

Use obsidian_dataview_query with vault="work" to run: TABLE file.name FROM #meeting WHERE file.cday = date(today)

🚀 Dica Profissional: Para uso em produção, configure inicialização automática na inicialização para que seu servidor e o Tailscale Funnel iniciem automaticamente sem intervenção manual.

Fachada do Conector ChatGPT

Clientes Claude e MCP locais podem se conectar diretamente ao /mcp. Conectores ChatGPT hospedados devem usar a fachada separada obsidian-chatgpt. A fachada reutiliza a lógica existente de vault, pesquisa e tarefas internamente, mas possui seu próprio processo, porta, fluxo de autorização OAuth/PKCE, capacidades com escopo e log de auditoria de escrita.

Use a fachada para rotas HTTPS públicas ou Tailscale Funnel. Mantenha o servidor MCP completo em localhost ou rotas privadas apenas na tailnet, a menos que esteja fazendo um teste local/de desenvolvimento explícito.

Iniciando a Fachada

Configure uma URL de recurso pública e uma chave secreta de aprovação de administrador, depois inicie a fachada:

export CHATGPT_FACADE_PUBLIC_URL="https://your-device.your-tailnet.ts.net"
export CHATGPT_FACADE_ADMIN_SECRET="$(openssl rand -hex 24)"
npm run build
npm run start:chatgpt

Se o mesmo hostname do Funnel também expõe outro conector ChatGPT, dê a esta fachada uma URL de recurso com escopo de caminho, como https://your-device.your-tailnet.ts.net/obsidian e roteie o prefixo /obsidian para a porta da fachada. A fachada atende tanto os caminhos de metadados well-known raiz quanto os qualificados por caminho para essa configuração. Nesse host compartilhado, crie o conector com https://your-device.your-tailnet.ts.net/obsidian/mcp.

Verifique a saúde:

curl "http://127.0.0.1:3020/health"

Para testes de superfície HTTP da fachada sem uma API Obsidian ativa, defina CHATGPT_FACADE_SKIP_OBSIDIAN_CHECK=true. Deixe sem definição para operação normal.

Exponha apenas a fachada através do Funnel:

make tailscale-funnel-chatgpt

OAuth e Escopos

A fachada publica metadados de descoberta OAuth:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/.well-known/openid-configuration

Ela armazena hashes de código de autorização, token de acesso e token de atualização localmente em CHATGPT_FACADE_STORE_PATH, não tokens brutos. Ela exige PKCE S256 para troca inicial de tokens, suporta rotação de token de atualização e valida tokens de portador por recurso, expiração e escopo antes de executar ações.

Escopos:

obsidian:read: search, fetch, task_query, latest_note
obsidian:write: create_task, update_task, append_note, create_note, create_daily_note
obsidian:dangerous-write: overwrite_note

A configuração do conector somente leitura é o padrão e é suportada concedendo apenas obsidian:read. overwrite_note não está disponível a menos que obsidian:dangerous-write seja explicitamente concedido.

Ações da Fachada

Todas as ações usam POST /chatgpt/actions com Authorization: Bearer <token>. Elas aceitam um campo opcional vault. A superfície pública padrão é intencionalmente menor que o conjunto completo de ferramentas MCP local.

Ação	Escopo	Descrição
`search`	`obsidian:read`	Pesquisa global limitada com trechos.
`fetch`	`obsidian:read`	Busca conteúdo de nota limitado por caminho do vault.
`task_query`	`obsidian:read`	Consulta de tarefas ciente do plugin Tasks.
`latest_note`	`obsidian:read`	Busca a nota mais recente modificada, opcionalmente limitada por caminho.
`create_task`	`obsidian:write`	Cria uma tarefa compatível com o plugin Tasks.
`update_task`	`obsidian:write`	Atualiza uma tarefa existente.
`append_note`	`obsidian:write`	Adiciona conteúdo ao final ou início da nota.
`create_note`	`obsidian:write`	Cria uma nota sem sobrescrever conteúdo existente.
`create_daily_note`	`obsidian:write`	Cria a nota diária de hoje ou uma especificada a partir do modelo de nota diária.
`overwrite_note`	`obsidian:dangerous-write`	Sobrescrita completa da nota para clientes explicitamente confiáveis.

Respostas de ações bem-sucedidas usam o mesmo envelope para ações HTTP e chamadas de ferramentas MCP da fachada:

{
  "success": true,
  "action": "create_daily_note",
  "vault": "default",
  "resultPath": "Daily/2026-07-03.md",
  "data": {
    "filePath": "Daily/2026-07-03.md"
  }
}

Ações de escrita incluem resultPath quando o caminho do vault afetado é conhecido. Ações de criação e atualização de tarefas também incluem taskLineNumber quando o número da linha está disponível.

Escritas são adicionadas ao log de auditoria JSONL local em CHATGPT_FACADE_AUDIT_PATH. A entrada de auditoria registra ação, id do cliente, escopos, caminho alvo, modo, caminho do resultado, status e um resumo de entrada limitado; ela não armazena transcrições brutas do ChatGPT ou corpos completos de notas. Operadores podem inspecionar entradas recentes com:

curl "http://127.0.0.1:3020/audit/recent?admin_secret=$CHATGPT_FACADE_ADMIN_SECRET"

Camada Legada em Processo

CHATGPT_LAYER_ENABLED=true ainda habilita a camada antiga de manifesto/ações em processo no transporte HTTP principal para compatibilidade local/de desenvolvimento. Essa camada usa autenticação por query-string MCP_AUTH_KEY e expõe ações mais amplas incluindo sobrescrita de página. Não a use como o caminho recomendado para conector ChatGPT hospedado.

Estrutura do Projeto

O codebase segue uma estrutura modular dentro do diretório src/:

src/
├── index.ts           # Entry point: Initializes and starts the server
├── config/            # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/        # Core MCP server logic and capability registration
│   ├── server.ts      # Server setup, transport handling, tool/resource registration
│   ├── resources/     # MCP Resource implementations (currently none)
│   ├── tools/         # MCP Tool implementations (subdirs per tool)
│   └── transports/    # Stdio and HTTP transport logic, auth middleware
├── services/          # Abstractions for external APIs or internal caching
│   ├── obsidianRestAPI/ # Typed client for Obsidian Local REST API
│   └── vaultManager/    # Multi-vault configuration and service management
├── types-global/      # Shared TypeScript type definitions (errors, etc.)
└── utils/             # Common utility functions (logger, error handler, security, etc.)

Para uma árvore de arquivos detalhada, execute npm run tree ou consulte docs/tree.md.

Serviço de Cache do Vault

Este servidor inclui um cache em memória inteligente, projetado para melhorar o desempenho e a resiliência ao interagir com seu vault.

Propósito e Benefícios

Desempenho: Ao armazenar em cache o conteúdo e os metadados dos arquivos, o servidor pode executar operações de busca muito mais rapidamente, especialmente em vaults grandes. Isso reduz o número de solicitações diretas à API REST Local do Obsidian, resultando em uma experiência mais ágil.
Resiliência: O cache atua como um fallback para a ferramenta obsidian_global_search. Se a busca pela API ao vivo falhar ou expirar, o servidor usa o cache de forma transparente para fornecer resultados, garantindo que a funcionalidade de busca permaneça disponível mesmo se a API do Obsidian estiver temporariamente indisponível.
Eficiência: O cache é projetado para ser eficiente. Ele realiza uma construção inicial na inicialização e, em seguida, atualiza periodicamente em segundo plano, verificando modificações nos arquivos, garantindo que permaneça razoavelmente atualizado sem polling constante e pesado da API.

Como Funciona

Inicialização: Quando habilitado, o VaultCacheService constrói um mapa em memória de todos os arquivos .md no seu vault, armazenando seu conteúdo e horários de modificação.
Atualização Periódica: O cache é atualizado automaticamente em um intervalo configurável (padrão de 10 minutos). Durante uma atualização, ele busca apenas o conteúdo de arquivos que são novos ou foram modificados desde a última verificação.
Atualizações Proativas: Após um arquivo ser modificado por meio de uma ferramenta como obsidian_update_file, o serviço atualiza proativamente o cache para esse arquivo específico, garantindo consistência imediata.
Fallback de Busca: A ferramenta obsidian_global_search primeiro tenta uma busca pela API ao vivo. Se isso falhar, ela automaticamente recorre à busca no cache em memória.

Configuração

O cache é habilitado por padrão, mas pode ser configurado por meio de variáveis de ambiente:

OBSIDIAN_ENABLE_CACHE: Defina como true (padrão) ou false para habilitar ou desabilitar o serviço de cache.
OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN: Define o intervalo em minutos para a atualização periódica em segundo plano. O padrão é 10.

Ferramentas

O Obsidian MCP Server fornece um conjunto de ferramentas para interagir com seu(s) vault(s), acionáveis por meio do Model Context Protocol.

Suporte a Múltiplos Vaults

Todas as ferramentas suportam um parâmetro opcional vault para especificar em qual vault operar:

Comportamento Padrão: Sem o parâmetro vault, as ferramentas usam o primeiro vault configurado
Vault Específico: Adicione vault: "vault-id" para direcionar um vault específico
Exemplo: obsidian_read_file(filePath="note.md", vault="work")

Nome da Ferramenta	Descrição	Argumentos Principais
`obsidian_read_file`	Recupera o conteúdo e os metadados de um arquivo.	`filePath`, `vault?`, `format?`, `includeStat?`
`obsidian_update_file`	Modifica um arquivo anexando, prefixando ou sobrescrevendo.	`targetType`, `content`, `vault?`, `targetIdentifier?`, `wholeFileMode`
`obsidian_search_replace`	Executa operações de busca e substituição em uma nota.	`targetType`, `replacements`, `vault?`, `useRegex?`, `replaceAll?`
`obsidian_global_search`	Busca conteúdo em todo o vault.	`query`, `vault?`, `searchInPath?`, `useRegex?`, `page?`, `pageSize?`
`obsidian_list_files`	Lista arquivos e subdiretórios em uma pasta.	`dirPath`, `vault?`, `fileExtensionFilter?`, `nameRegexFilter?`
`obsidian_manage_frontmatter`	Obtém, define ou exclui chaves no frontmatter de uma nota.	`filePath`, `operation`, `key`, `vault?`, `value?`
`obsidian_manage_tags`	Adiciona, remove ou lista tags em uma nota.	`filePath`, `operation`, `tags`, `vault?`
`obsidian_delete_file`	Exclui permanentemente um arquivo do vault.	`filePath`, `vault?`
`obsidian_dataview_query`	Executa consultas DQL do Dataview no seu vault.	`query`, `vault?`, `format?`
`obsidian_task_query`	Busca e analisa tarefas em todo o vault.	`vault?`, `status?`, `dateRange?`, `folder?`, `priority?`, `format?`
`obsidian_periodic_notes`	Cria e gerencia notas diárias, semanais, mensais e anuais.	`operation`, `periodType`, `vault?`, `date?`, `content?`, `append?`
`obsidian_block_reference`	Trabalha com referências de bloco e operações de cabeçalho.	`operation`, `filePath`, `vault?`, `heading?`, `content?`, `blockId?`
`obsidian_graph_analysis`	Analisa conexões de notas e relacionamentos do vault.	`operation`, `vault?`, `filePath?`, `minConnections?`, `maxDepth?`
`obsidian_template_system`	Cria arquivos a partir de modelos com substituição de variáveis.	`operation`, `vault?`, `templatePath?`, `targetPath?`, `variables?`
`obsidian_smart_linking`	Obtém sugestões e recomendações inteligentes de links.	`operation`, `vault?`, `filePath?`, `content?`, `maxSuggestions?`

Nota: Todas as ferramentas suportam tratamento abrangente de erros, roteamento para múltiplos vaults e retornam respostas JSON estruturadas.

Licença

Este projeto é licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para detalhes.

Atribuição

Esta versão aprimorada é baseada no excelente trabalho de cyanheads no projeto original obsidian-mcp-server. Todo o crédito pela funcionalidade principal e arquitetura vai para o autor original.

Aprimoramentos neste fork:

Suporte a Múltiplos Vaults: Acesso simultâneo a vários vaults do Obsidian com roteamento específico por vault
Integração e correções de compatibilidade com Claude.ai Remote MCP
Integração com Tailscale Funnel para acesso remoto seguro
Camada de transporte HTTP aprimorada com separação de autenticação (MCP_AUTH_KEY)
Consulta avançada de tarefas com integração ao plugin Tasks
5 Novas Ferramentas Avançadas: Notas periódicas, referências de bloco, análise de grafo, sistema de modelos e vinculação inteligente
Configuração pronta para produção para uso empresarial

Construído com o Model Context Protocol
Aprimorado para integração remota com Claude.ai