Obsidian GitHub MCP

Conecta asistentes de IA a bóvedas de Obsidian almacenadas en repositorios de GitHub, permitiéndoles leer, buscar y analizar tus notas y documentación.

GitHub

Prueba este MCPPatrocinado

Documentación

Obsidian GitHub MCP

Un servidor de Model Context Protocol (MCP) que conecta asistentes de IA con repositorios de GitHub que contienen bóvedas de Obsidian. Este servidor permite una integración perfecta con tu base de conocimiento alojada en GitHub, permitiendo a los asistentes de IA leer, buscar y analizar tus notas y documentación de Obsidian.

¿Por Qué Esta Herramienta?

Muchos usuarios de Obsidian almacenan sus bóvedas en GitHub para realizar copias de seguridad, control de versiones y colaboración. Este servidor MCP cierra la brecha entre tu bóveda de Obsidian alojada en GitHub y los asistentes de IA, permitiendo:

Acceso a la Base de Conocimiento: Recupera notas y documentos específicos de tu bóveda de Obsidian
Búsqueda Inteligente: Encuentra contenido relevante en toda tu base de conocimiento
Seguimiento de Evolución: Observa cómo tus ideas y notas se han desarrollado con el tiempo
Integración de Tareas: Conéctate con issues y flujos de trabajo de gestión de proyectos

Características

Acceso a Repositorios de GitHub: Conéctate a cualquier repositorio de GitHub que contenga tu bóveda de Obsidian
Implementación Segura de Tipos: Escrito en TypeScript con definiciones de tipos exhaustivas
Validación de Entradas: Validación robusta para todas las entradas de API mediante esquemas Zod
Manejo de Errores: Manejo de errores elegante con mensajes informativos
Integración MCP: Compatibilidad total con Claude, Cursor, Windsurf, Cline y otros hosts MCP

Herramientas Disponibles

Acceso a la Base de Conocimiento

getFileContents: Recupera el contenido de notas, documentos o archivos específicos de tu bóveda de Obsidian
searchFiles: Búsqueda mejorada con múltiples modos:
- filename: Encuentra archivos por nombre exacto (perfecto para búsquedas tipo "OKR 2025")
- path: Busca en cualquier parte de las rutas de archivo
- content: Busca dentro del contenido de los archivos
- all: Búsqueda exhaustiva en nombres de archivo, rutas y contenido

Integración de Gestión de Proyectos

searchIssues: Busca issues y discusiones relacionadas con tus proyectos de base de conocimiento
getCommitHistory: Realiza un seguimiento de cómo ha evolucionado tu base de conocimiento con el tiempo mediante un historial de commits y diffs detallado

Casos de Uso

Para Trabajadores del Conocimiento

Asistente de Investigación: La IA puede acceder a tus notas de investigación y materiales de referencia
Soporte de Escritura: Extrae información de contexto relevante de tu base de conocimiento
Desarrollo de Ideas: Realiza un seguimiento de cómo han evolucionado los conceptos en tus notas

Para Desarrolladores

Acceso a Documentación: Recupera documentación de proyectos y notas técnicas
Diarios de Aprendizaje: Accede a tus notas de aprendizaje y ejemplos de código
Planificación de Proyectos: Integra con issues de GitHub para una gestión integral de proyectos

Para Estudiantes y Académicos

Materiales de Estudio: Accede a apuntes de clase y guías de estudio
Artículos de Investigación: Recupera notas de investigación y citas
Colaboración: Trabaja con bases de conocimiento compartidas almacenadas en GitHub

Instalación

Usando Smithery (Recomendado)

La forma más sencilla de instalar Obsidian GitHub MCP es usando 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

Instalación Manual

npm install obsidian-github-mcp

Configuración

Añade el servidor a tu archivo de configuración de MCP con la siguiente configuración:

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

Variables de Entorno Requeridas

GITHUB_TOKEN: Tu token de acceso personal de GitHub (crea uno aquí)
GITHUB_OWNER: El propietario/organización del repositorio de GitHub
GITHUB_REPO: El nombre del repositorio que contiene tu bóveda de Obsidian

Permisos del Token de GitHub

Tu token de GitHub necesita los siguientes permisos:

repo (para repositorios privados) o public_repo (para repositorios públicos)
read:org (si accedes a repositorios de organizaciones)

Flujos de Trabajo de Ejemplo

Accediendo a Tus Notas Diarias

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

Encontrando Archivos por Nombre (¡Perfecto para el ejemplo "OKR 2025"!)

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

Encontrando Archivos por Ruta

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

Encontrando Investigación sobre un Tema (Búsqueda de Contenido)

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

Búsqueda Exhaustiva (Nombre de Archivo, Ruta y Contenido)

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

Sintaxis Avanzada de Búsqueda de GitHub

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

Seguimiento de la Evolución del Conocimiento

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

Consejos de Búsqueda y Solución de Problemas

¿No Puedes Encontrar Tu Archivo por Nombre?

Problema: Buscar "OKR 2025" no encuentra tu archivo llamado "OKR 2025.md"

Solución: Usa el parámetro searchIn: "filename":

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

Técnicas Avanzadas de Búsqueda

Frases Exactas: Usa comillas para búsquedas de varias palabras

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

Extensiones de Archivo: Encuentra tipos de archivo específicos
```
{
  "query": "path:*.md",
  "searchIn": "content"
}
```

Específico de Directorio: Busca dentro de carpetas

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

Estructura del Proyecto

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 Desarrolladores

Si estás interesado en contribuir a este proyecto o en desarrollar tus propias herramientas con este servidor, consulta la Guía de Desarrollo.

Comandos de Desarrollo

pnpm install - Instala las dependencias
pnpm run build - Compila el proyecto
pnpm run dev - Ejecuta en modo de desarrollo con inspector
pnpm run inspector - Inicia el inspector de MCP para pruebas

Migración desde mcp-private-github-search

Si estás migrando desde el paquete anterior mcp-private-github-search:

Actualiza el nombre del paquete en tu configuración:

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

La funcionalidad sigue siendo la misma: todas las herramientas existentes funcionan de manera idéntica
Considera los nuevos casos de uso y flujos de trabajo centrados en Obsidian

Aprende Más

Para obtener más información sobre el ecosistema MCP, consulta:

Documentación del Model Context Protocol: Cobertura detallada de la arquitectura y los principios de diseño de MCP
Smithery - Registro de Servidores MCP: Directrices para publicar servidores MCP
Documentación del SDK de TypeScript de MCP: Documentación exhaustiva del SDK de TypeScript
Obsidian: La aplicación de gestión del conocimiento que inspiró esta herramienta

Acerca de Hint Services

"El futuro ya está aquí, solo que está distribuido de manera desigual"

— William Gibson, Autor

Hint Services es una consultora boutique con la misión de desarrollar y expandir cómo las interfaces de usuario aprovechan la tecnología de inteligencia artificial. Arquitectamos ambición en la intersección de la IA y la Experiencia de Usuario, fundada y dirigida por Ben Hofferber.

Ofrecemos talleres especializados de IA para equipos de diseño que buscan adoptar herramientas de IA sin convertirse en desarrolladores. Aprende más sobre nuestra formación y talleres.