TheBrain MCP Server

Interactúa con el sistema de gestión de conocimiento de TheBrain usando su API.

GitHub
16
Prueba este MCPPatrocinado

Documentación

Servidor MCP de TheBrain

Un servidor MCP (Protocolo de Contexto de Modelo) que permite a los asistentes de IA interactuar con el sistema de gestión de conocimiento de TheBrain. Este servidor proporciona acceso integral a la API de TheBrain, centrándose en la interacción en lenguaje natural con las potentes capacidades de gestión de conocimiento de TheBrain.

🔧 ¿Qué es un servidor MCP?

MCP (Protocolo de Contexto de Modelo) es un estándar que permite a los asistentes de IA como Claude conectarse a herramientas y servicios externos. Piénsalo como un traductor entre el lenguaje natural y las APIs de software.

Cómo funciona:

You → Claude → MCP Server → TheBrain API → Your Brain
  1. Tú dices: "Crea un proyecto con tres fases"
  2. Claude entiende lo que quieres lograr
  3. El servidor MCP traduce esto en llamadas específicas a la API de TheBrain
  4. La API de TheBrain crea los pensamientos y conexiones
  5. Tu cerebro se actualiza con la nueva estructura

La magia es que no necesitas saber ningún detalle técnico — ¡solo describe lo que quieres en lenguaje sencillo!

🚀 Lo que realmente funciona

✅ Funcionalidad principal (funcionando)

  • Gestión de contenido: Crear, actualizar y eliminar pensamientos y notas
  • Archivos adjuntos: Subir imágenes, PDFs, documentos a pensamientos
  • Referencias web: Adjuntos de URL con extracción automática de títulos
  • Notas enriquecidas: Soporte completo de Markdown con contenido incrustado
  • Mapeo de relaciones: Conectar pensamientos con relaciones significativas
  • Búsqueda: Búsqueda de texto completo en pensamientos, notas y adjuntos
  • Gestión de cerebros: Cambiar entre múltiples cerebros sin problemas
  • Interfaz de lenguaje natural: Describe lo que quieres, Claude maneja los detalles

❌ Problemas y limitaciones actuales

🚨 Problemas importantes de estilo visual

La mayor limitación: Las propiedades visuales no se aplican realmente a pesar de las respuestas exitosas de la API.

  • ❌ Colores de pensamientos: La API acepta colores pero no aparecen en TheBrain
  • ❌ Colores de enlaces: Problema similar — se aceptan pero no se aplican
  • ❌ Grosor de enlaces: La API reporta éxito pero el grosor no cambia
  • ❌ Formato visual: Todas las funciones de estilo visual están actualmente no funcionales

🐛 Otros problemas conocidos

  • Problemas de conexión intermitentes: Errores de "Campo requerido" después de operaciones exitosas
  • Limitaciones de notas largas: Problemas con contenido Markdown muy largo (mantener bajo 10k caracteres)
  • Sensibilidad a rutas de archivo: Requiere rutas de archivo absolutas; las rutas relativas pueden fallar
  • Tiempo de conexión: Condición de carrera en la inicialización de MCP que causa fallos esporádicos
  • Restricciones de memoria: Archivos adjuntos grandes pueden causar tiempos de espera
  • Limitaciones de búsqueda: Consultas complejas a veces devuelven resultados incompletos

📋 Dependencias y restricciones de la API

  • Operaciones de usuario único: Sin funciones de colaboración en tiempo real
  • Sin operaciones masivas: No se pueden importar/exportar grandes conjuntos de datos de manera eficiente
  • Conectividad de API requerida: No hay modo sin conexión disponible
  • Limitaciones de la API de TheBrain: Limitado por las capacidades existentes de la API
  • Autenticación requerida: Debe tener una clave de API válida de TheBrain

🛠 Soluciones alternativas actuales

Hasta que se arregle el estilo visual, usa estas alternativas:

  • Emojis para distinguir: 🟢🟡🔴⚪🔵 en lugar de colores
  • Nombres descriptivos: "🔴 Tarea urgente" en lugar de pensamientos de colores
  • Notas Markdown enriquecidas: Usa formato dentro de las notas para organización visual
  • Estructura jerárquica: Confía en las relaciones padre/hijo para la organización

Instalación

  1. Clona este repositorio:
git clone https://github.com/redmorestudio/thebrain-mcp.git
cd thebrain-mcp
  1. Instala las dependencias:
npm install
  1. Crea un archivo .env con tu clave de API:
THEBRAIN_API_KEY=your_api_key_here
THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id

Configuración

Para Claude Desktop

Añade a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "thebrain": {
      "command": "node",
      "args": ["/absolute/path/to/thebrain-mcp/index.js"],
      "env": {
        "THEBRAIN_API_KEY": "your_api_key_here"
      }
    }
  }
}

⚠️ Importante: Usa rutas de archivo absolutas en la configuración y para archivos adjuntos.

Depuración y solución de problemas

Problemas comunes y soluciones

Errores de "Campo requerido":

  • Reinicia Claude Desktop
  • Verifica que el archivo .env tenga la clave de API correcta
  • Siempre establece el cerebro activo primero: "Establece mi cerebro activo como [nombre]"

Fallos en la subida de archivos:

  • Usa rutas de archivo absolutas: /Users/username/Documents/file.pdf
  • Verifica los permisos y la existencia de los archivos
  • Mantén tamaños de archivo razonables (< 50MB)

Problemas con notas largas:

  • Mantén las notas bajo 10,000 caracteres
  • Divide el contenido grande en múltiples pensamientos
  • Usa adjuntos para documentos extensos

Modo de depuración:

VERBOSE=true node index.js

Herramientas disponibles (más de 25 funciones)

Gestión de cerebros

  • list_brains - Lista todos los cerebros disponibles
  • get_brain - Obtiene detalles del cerebro
  • set_active_brain - Establece el cerebro activo para operaciones
  • get_brain_stats - Obtiene estadísticas completas del cerebro

Operaciones de pensamiento

  • create_thought - Crea pensamientos (las propiedades visuales no funcionan)
  • get_thought - Recupera detalles del pensamiento
  • update_thought - Actualiza propiedades del pensamiento
  • delete_thought - Elimina un pensamiento
  • search_thoughts - Busca en todo el cerebro
  • get_thought_graph - Obtiene pensamiento con todas las conexiones
  • get_types - Lista todos los tipos de pensamiento
  • get_tags - Lista todas las etiquetas

Operaciones de enlaces

  • create_link - Crea enlaces entre pensamientos (el estilo no funciona)
  • update_link - Modifica propiedades de enlaces
  • get_link - Obtiene detalles del enlace
  • delete_link - Elimina un enlace

Operaciones de adjuntos

  • add_file_attachment - Adjunta archivos/imágenes a pensamientos ✅
  • add_url_attachment - Adjunta URLs web ✅
  • get_attachment - Obtiene metadatos del adjunto
  • get_attachment_content - Descarga contenido del adjunto
  • delete_attachment - Elimina adjuntos
  • list_attachments - Lista adjuntos del pensamiento

Operaciones de notas

  • get_note - Recupera notas en markdown/html/texto ✅
  • create_or_update_note - Crea o actualiza notas ✅
  • append_to_note - Añade contenido a notas existentes ✅

Funciones avanzadas

  • get_modifications - Ve el historial de modificaciones del cerebro

Ejemplos de uso (lo que realmente funciona)

Organización de proyectos

You: "Create a project called 'Kitchen Renovation'"
Claude: Creates central project thought

You: "Add phases for planning, demolition, and installation"  
Claude: Creates connected sub-thoughts for each phase

You: "Attach my contractor quotes to the planning phase"
Claude: Uploads files to the planning thought

You: "Add a detailed note about the timeline to the project"
Claude: Creates rich markdown note with your timeline

Investigación y gestión de conocimiento

You: "Create a research topic about sustainable energy"
Claude: Sets up main research thought

You: "Add sub-topics for solar, wind, and hydro power"
Claude: Creates organized thought hierarchy

You: "Attach relevant papers and web articles"
Claude: Adds file and URL attachments

You: "Search for everything related to efficiency"
Claude: Finds all relevant thoughts and content

🔮 Hoja de ruta y desarrollo futuro

Prioridades inmediatas (v1.2.0)

  • 🚨 Arreglar estilo visual: Investigar por qué los colores/grosor no se aplican
  • 🔧 Estabilidad de conexión: Resolver problemas de tiempo/condición de carrera de MCP
  • 📝 Soporte de notas largas: Mejor manejo de contenido Markdown extenso
  • 🛡️ Manejo de errores: Fallos y recuperación más elegantes

Mejoras futuras

  • Operaciones masivas para organización a gran escala
  • Plantillas mejoradas para flujos de trabajo comunes
  • Optimizaciones de rendimiento para cerebros complejos
  • Capacidades sin conexión y almacenamiento en caché

Arquitectura técnica

Qué hace especial a este servidor

  • Interfaz de lenguaje natural: No se requiere conocimiento técnico
  • Cobertura completa de la API: Más de 25 herramientas que abarcan todas las operaciones de TheBrain
  • Manejo robusto de errores: Fallos elegantes y mensajes de error claros
  • Diseño modular: Arquitectura de código limpia y mantenible
  • Listo para producción: Registro, pruebas y documentación adecuados

Estado actual

  • Versión: 1.1.0 (junio de 2025)
  • Funcionalidad principal: ✅ Completa y funcionando
  • Propiedades visuales: ❌ Problemas importantes que necesitan investigación
  • Estabilidad: 🟡 Generalmente estable con problemas de conexión intermitentes

Contribuciones

¡Las contribuciones son bienvenidas! Áreas donde se necesita especialmente ayuda:

  • Investigación de estilo visual: ¿Por qué los colores/grosor no se aplican?
  • Estabilidad de conexión: Depuración de condiciones de carrera de MCP
  • Optimización de rendimiento: Manejo de cerebros grandes
  • Documentación: Más ejemplos de uso y tutoriales

No dudes en enviar problemas o solicitudes de extracción.

Licencia

Licencia MIT — consulta el archivo LICENCIA para más detalles.

Soporte

⚠️ Recomendación actual: Usa este servidor para gestión de contenido y organización con interacción en lenguaje natural. No confíes en las funciones de estilo visual hasta que se arreglen. La funcionalidad principal es sólida y muy útil para gestionar contenido de TheBrain a través de la conversación.