Obsidian GitHub MCP

Conect

GitHub
9
Experimente este MCPPatrocinado

Documentação

smithery badge npm version

Obsidian GitHub MCP

Um servidor Model Context Protocol (MCP) que conecta assistentes de IA a repositórios GitHub contendo cofres (vaults) do Obsidian. Este servidor permite integração perfeita com sua base de conhecimento armazenada no GitHub, permitindo que assistentes de IA leiam, pesquisem e analisem suas notas e documentação do Obsidian.

Por que esta ferramenta?

Muitos usuários do Obsidian armazenam seus cofres no GitHub para backup, versionamento e colaboração. Este servidor MCP preenche a lacuna entre seu cofre Obsidian hospedado no GitHub e assistentes de IA, permitindo:

  • Acesso à Base de Conhecimento: Recupere notas e documentos específicos do seu cofre Obsidian
  • Busca Inteligente: Encontre conteúdo relevante em toda a sua base de conhecimento
  • Acompanhamento de Evolução: Veja como suas ideias e notas se desenvolveram ao longo do tempo
  • Integração com Tarefas: Conecte-se a issues e fluxos de trabalho de gerenciamento de projetos

Recursos

  • Acesso a Repositórios GitHub: Conecte-se a qualquer repositório GitHub que contenha seu cofre Obsidian
  • Implementação Type-Safe: Escrito em TypeScript com definições de tipos abrangentes
  • Validação de Entrada: Validação robusta para todas as entradas de API usando esquemas Zod
  • Tratamento de Erros: Tratamento gracioso de erros com mensagens informativas
  • Integração MCP: Compatibilidade total com Claude, Cursor, Windsurf, Cline e outros hosts MCP

Ferramentas Disponíveis

Acesso à Base de Conhecimento

  • getFileContents: Recupere o conteúdo de notas, documentos ou arquivos específicos do seu cofre Obsidian
  • searchFiles: Busca aprimorada com múltiplos modos:
    • filename: Encontre arquivos pelo nome exato (perfeito para buscas do tipo "OKR 2025")
    • path: Pesquise em qualquer lugar nos caminhos dos arquivos
    • content: Pesquise dentro do conteúdo dos arquivos
    • all: Busca abrangente em nomes de arquivos, caminhos e conteúdo

Integração com Gerenciamento de Projetos

  • searchIssues: Pesquise issues e discussões relacionadas aos seus projetos de base de conhecimento
  • getCommitHistory: Acompanhe como sua base de conhecimento evoluiu ao longo do tempo com histórico detalhado de commits e diffs

Casos de Uso

Para Profissionais do Conhecimento

  • Assistente de Pesquisa: A IA pode acessar suas notas de pesquisa e materiais de referência
  • Suporte à Escrita: Obtenha informações contextuais relevantes da sua base de conhecimento
  • Desenvolvimento de Ideias: Acompanhe como conceitos evoluíram em suas notas

Para Desenvolvedores

  • Acesso à Documentação: Recupere documentação de projetos e notas técnicas
  • Diários de Aprendizado: Acesse suas notas de aprendizado e exemplos de código
  • Planejamento de Projetos: Integre-se a issues do GitHub para gerenciamento abrangente de projetos

Para Estudantes e Acadêmicos

  • Materiais de Estudo: Acesse notas de aula e guias de estudo
  • Artigos de Pesquisa: Recupere notas de pesquisa e citações
  • Colaboração: Trabalhe com bases de conhecimento compartilhadas armazenadas no GitHub

Instalação

Usando Smithery (Recomendado)

A maneira mais fácil de instalar o Obsidian GitHub MCP é usando o Smithery:

# For Claude Desktop
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client claude

# For Cursor
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cursor

# For Windsurf
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client windsurf

# For Cline
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cline

Instalação Manual

npm install obsidian-github-mcp

Configuração

Adicione o servidor ao seu arquivo de configurações MCP com a seguinte configuração:

{
  "mcpServers": {
    "obsidianGithub": {
      "command": "npx",
      "args": ["-y", "obsidian-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your-github-token",
        "GITHUB_OWNER": "your-github-username",
        "GITHUB_REPO": "your-obsidian-vault-repo"
      }
    }
  }
}

Variáveis de Ambiente Necessárias

  • GITHUB_TOKEN: Seu token de acesso pessoal do GitHub (crie um aqui)
  • GITHUB_OWNER: O proprietário/organização do repositório GitHub
  • GITHUB_REPO: O nome do repositório que contém seu cofre Obsidian

Permissões do Token GitHub

Seu token do GitHub precisa das seguintes permissões:

  • repo (para repositórios privados) ou public_repo (para repositórios públicos)
  • read:org (se estiver acessando repositórios de organizações)

Exemplos de Fluxos de Trabalho

Acessando Suas Notas Diárias

{
  "tool": "getFileContents",
  "arguments": {
    "filePath": "Daily Notes/2024-01-15.md"
  }
}

Encontrando Arquivos por Nome (Perfeito para o exemplo "OKR 2025"!)

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

Encontrando Arquivos por Caminho

{
  "tool": "searchFiles",
  "arguments": {
    "query": "Daily Notes",
    "searchIn": "path"
  }
}

Encontrando Pesquisas sobre um Tópico (Busca de Conteúdo)

{
  "tool": "searchFiles",
  "arguments": {
    "query": "machine learning algorithms",
    "searchIn": "content",
    "perPage": 10
  }
}

Busca Abrangente (Nome de Arquivo, Caminho e Conteúdo)

{
  "tool": "searchFiles",
  "arguments": {
    "query": "project planning",
    "searchIn": "all"
  }
}

Sintaxe Avançada de Busca no GitHub

{
  "tool": "searchFiles",
  "arguments": {
    "query": "path:*.md extension:md",
    "searchIn": "content"
  }
}

Acompanhando a Evolução do Conhecimento

{
  "tool": "getCommitHistory",
  "arguments": {
    "days": 30,
    "includeDiffs": true,
    "maxCommits": 10
  }
}

Dicas de Busca e Solução de Problemas

Não Consegue Encontrar Seu Arquivo pelo Nome?

Problema: Buscar por "OKR 2025" não encontra seu arquivo chamado "OKR 2025.md"

Solução: Use o parâmetro searchIn: "filename":

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

Técnicas Avançadas de Busca

  1. Frases Exatas: Use aspas para buscas com múltiplas palavras

    {
  "query": "\"project planning 2025\"",
  "searchIn": "content"
}

  2. Extensões de Arquivo: Encontre tipos de arquivo específicos

    {
  "query": "path:*.md",
  "searchIn": "content"
}

  3. Específico de Diretório: Pesquise dentro de pastas

    {
  "query": "path:\"Daily Notes/\"",
  "searchIn": "content"
}

Estrutura do Projeto

obsidian-github-mcp/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   └── github/           # GitHub API integration
│       ├── client.ts     # GitHub client implementation
│       └── types.ts      # TypeScript type definitions
├── docs/                 # Documentation
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

Para Desenvolvedores

Se você está interessado em contribuir com este projeto ou desenvolver suas próprias ferramentas com este servidor, consulte o Guia de Desenvolvimento.

Comandos de Desenvolvimento

  • pnpm install - Instalar dependências
  • pnpm run build - Compilar o projeto
  • pnpm run dev - Executar em modo de desenvolvimento com inspetor
  • pnpm run inspector - Iniciar o inspetor MCP para testes

Migração do mcp-private-github-search

Se você está migrando do pacote mais antigo mcp-private-github-search:

  1. Atualize o nome do pacote na configuração:

    {
  "mcpServers": {
    "obsidianGithub": {
      "command": "npx",
      "args": ["-y", "obsidian-github-mcp"]
    }
  }
}

  2. A funcionalidade permanece a mesma - todas as ferramentas existentes funcionam de forma idêntica

  3. Considere os novos casos de uso e fluxos de trabalho focados no Obsidian

Saiba Mais

Para mais informações sobre o ecossistema MCP, consulte:

Sobre a Hint Services

"O futuro já está aqui, apenas distribuído de forma desigual"

— William Gibson, Autor

A Hint Services é uma consultoria boutique com a missão de desenvolver e expandir como as interfaces de usuário aproveitam a tecnologia de inteligência artificial. Arquitetamos ambição na interseção entre IA e Experiência do Usuário, fundada e liderada por Ben Hofferber.

Oferecemos workshops especializados de IA para equipes de design que desejam adotar ferramentas de IA sem se tornarem desenvolvedores. Saiba mais sobre nossos treinamentos e workshops.