{
  "markdown": "# second-brain-mcp\n\n**Español** · [English](README.en.md)\n\n![npm](https://img.shields.io/npm/v/%40toportal%2Fsecond-brain-mcp)\n![tests](https://github.com/Portaltocoding/second-brain-mcp/actions/workflows/test.yml/badge.svg)\n![node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)\n![license](https://img.shields.io/badge/license-MIT-blue)\n\nTu segundo cerebro, en tu Obsidian, hablando con tu asistente.\n\nEsto es un servidor MCP que convierte una carpeta de Markdown en un **second brain\nde verdad**: capturas lo que lees, lo conviertes en ideas con tus palabras, y esas\nideas se conectan entre sí hasta formar un grafo que *piensa contigo*: cuando\ntrabajas en algo, las notas relacionadas aparecen solas.\n\nTodo en castellano. Todo en ficheros tuyos. Sin bases de datos, sin nube, sin magia\nque no puedas abrir con un editor de texto.\n\n## ¿Cómo se siente?\n\nLe dices a tu asistente:\n\n> «Estoy leyendo Hábitos Atómicos, apunta esto: el entorno decide más que la\n> fuerza de voluntad»\n\ny él crea la lectura si no existía, guarda el apunte, y cuando esa idea madure la\nconvierte en una nota permanente conectada al concepto `[[Hábitos]]`, que a su\nvez acumula todo lo que has pensado sobre el tema, venga del libro que venga.\n\nSemanas después, trabajando en otra cosa, preguntas por diseñar tu rutina de\nmañanas y el sistema te trae de vuelta *«El entorno decide por ti»* con el párrafo\nexacto. Eso es el segundo cerebro: no recordar tú, que recuerde él.\n\n## El mapa\n\nCada etiqueta es `método / qué es`; en las dos puertas principales va también la\nfrase que lo dispara:\n\n```\n                             tú + tu asistente\n                                  │      ▲\n                ingerir / ingesta │      │ resurgir / recuerdo\n                   «añade esto»   ▼      │   «¿qué sé de esto?»\n                           ┌──────────────┐\n                           │ second-brain │\n                           └───────┬──────┘\n                     clasifica lo que entra\n       ┌───────────────────────────┼───────────────────────────┐\n       │ lectura_crear / ficha     │ nota_permanente / idea    │ mini_nota / apunte\n       │ lectura_nota / apuntes    │                           │\n       ▼                           ▼                           ▼\n┌──────────────┐            ┌─────────────┐           ┌────────────────┐\n│ 40-Lecturas/ │            │  50-Notas/  │           │ proyecto/brain/│\n│ lo que entra │            │ lo que queda│           │ el taller      │\n└──────┬───────┘            └──────┬──────┘           └────────┬───────┘\n       │                           │                           │\n       │ nota_permanente /         │ temas                     │ mini_promover /\n       │ la idea madura            │                           │ madura o resuena\n       └──────────────────────────▶│───────────┐               │\n                                   │           ▼               │\n              nota_enlazar /       │   ┌───────────────┐       │\n              relacionar con       │   │ 60-Conceptos/ │◀──────┘\n              motivo (2-3 máx)     ▼   │ lo que conecta│\n                             otras ideas└───────────────┘\n\n     jardin / poda «¿cómo está el jardín?» · concepto_fusionar / coser nodos\n     vault_buscar / grep «busca dónde dije X» · mini_listar / cosecha del taller\n```\n\n## Instalación\n\n### Lo más rápido: una línea, sin configurar nada\n\nSi usas **Claude Code**:\n\n```bash\nclaude mcp add --scope user second-brain -- npx -y @toportal/second-brain-mcp\n```\n\nCon cualquier otro cliente MCP:\n\n```json\n{\n  \"mcpServers\": {\n    \"second-brain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@toportal/second-brain-mcp\"]\n    }\n  }\n}\n```\n\nSin variables de entorno y sin decidir nada: tu cerebro se monta en\n`~/second-brain`, con las tres carpetas y la portada listas. Dile a tu asistente\n«hazme el onboarding de mi second brain» y ya estás dentro.\n\n¿Prefieres que viva en tu vault de Obsidian de siempre? Añade\n`BRAIN_VAULT=/ruta/a/tu/vault` y punto — el servidor solo escribe en tres\nsubcarpetas y no toca nada más. Y si ya empezaste en el vault por defecto,\nmueve la carpeta a donde quieras y apunta `BRAIN_VAULT` allí: son ficheros\nMarkdown, no hay nada que migrar.\n\n### Sin terminal: doble clic y listo\n\nSi usas **Claude Desktop** y no quieres saber nada de comandos ni de JSON,\ndescarga\n[`second-brain.mcpb`](https://github.com/Portaltocoding/second-brain-mcp/releases/latest/download/second-brain.mcpb)\ny haz doble clic: Claude Desktop lo abre, te pide elegir la carpeta donde\nvivirá tu cerebro (tu vault de Obsidian si tienes, o una carpeta vacía\ncualquiera) y ya está. No necesitas instalar Node ni tocar ningún fichero de\nconfiguración. Y si además quieres ver tu cerebro dibujado como un grafo,\ninstala [Obsidian](https://obsidian.md) y abre esa misma carpeta como vault.\n\n### Con terminal, eligiendo tú la carpeta\n\nNecesitas Node 18 o más nuevo. Con **Claude Code**, a nivel de usuario\n(disponible en todos tus proyectos):\n\n```bash\nclaude mcp add --scope user second-brain \\\n  --env BRAIN_VAULT=/ruta/a/tu/vault \\\n  -- npx -y @toportal/second-brain-mcp\n```\n\nCon cualquier otro cliente MCP:\n\n```json\n{\n  \"mcpServers\": {\n    \"second-brain\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@toportal/second-brain-mcp\"],\n      \"env\": { \"BRAIN_VAULT\": \"/ruta/a/tu/vault\" }\n    }\n  }\n}\n```\n\nY listo. La primera nota crea las carpetas que hagan falta.\n\nUna salvaguarda: si la ruta que configuras no existe **y su carpeta contenedora\ntampoco**, el servidor da por hecho que es un error al escribirla y te lo dice en\nla conversación en vez de plantarte un vault en una carpeta fantasma. Si el padre\nexiste, la crea sin preguntar: eso es lo que querías.\n\nSi prefieres dejar el vault montado desde el principio (carpetas + portada), hay\nandamiaje:\n\n```bash\nnpx -y @toportal/second-brain-mcp --init /ruta/a/tu/vault\n```\n\nEs idempotente: sobre un vault que ya existe no toca nada.\n\n### Variables de entorno\n\n| Variable | Qué hace | Por defecto |\n|---|---|---|\n| `BRAIN_VAULT` | La ruta de tu vault (también vale como primer argumento). Si no la pones, se usa el vault por defecto | `~/second-brain` |\n| `BRAIN_MODO` | Motor de `resurgir`: `lexico` o `rag` | `lexico` |\n| `BRAIN_RAG_UMBRAL` | A partir de cuántas notas puede sugerirse el modo rag | `50` |\n\n## Tu primera sesión\n\nNo te la tienes que inventar: dile a tu asistente «hazme el onboarding de mi\nsecond brain» (es el prompt `empezar`; en Claude Code aparece como el comando\n`/mcp__second-brain__empezar`) y él te guía paso a paso: mira cómo está tu\nvault, planta contigo la primera lectura y la primera idea con tus propias\npalabras, te enseña qué devuelve `resurgir` con tu material, y te deja la\nchuleta de los tres gestos del día a día. Si el vault ya tiene contenido no te\ntrata de nuevo: te hace un tour de lo que hay.\n\n## Pruébalo en 30 segundos\n\nEl repo trae un vault de ejemplo ya tejido en `ejemplo/`, con dos lecturas,\ncuatro ideas y cuatro conceptos conectados entre sí, así que puedes ver el\ngrafo funcionando antes de haber escrito una sola nota tuya:\n\n```bash\ngit clone https://github.com/Portaltocoding/second-brain-mcp\ncd second-brain-mcp && npm install\nclaude mcp add second-brain --env BRAIN_VAULT=$PWD/ejemplo -- node src/server.js\n```\n\nY le preguntas a tu asistente algo como «¿qué sé yo sobre la fuerza de\nvoluntad?». También puedes abrir la carpeta `ejemplo/` como vault en Obsidian\ny ver el grafo dibujado.\n\n## Una sesión de verdad\n\nAsí se ve el día a día, sin aprenderse ninguna tool:\n\n> **Tú:** añade esto a mi second brain, lo más importante: *\"llevo semanas\n> notando que si dejo el móvil en otra habitación por la mañana me salen dos\n> horas de trabajo del tirón, y si lo tengo al lado voy a rachas de diez\n> minutos entre miradas\"*\n>\n> **Asistente:** esto es un pensamiento tuyo ya digerido, así que va como nota\n> permanente en modo destilar. La idea fuerte que veo: **«La distancia física\n> al móvil marca la profundidad del trabajo»**, con los conceptos `Foco` y\n> `Entorno`, que ya existen en tu grafo. ¿La creo así?\n>\n> **Tú:** dale\n>\n> **Asistente:** creada. Y resuena fuerte con **«El foco se diseña, no se\n> invoca»** (score 8): las dos hablan de preparar el entorno en vez de confiar\n> en la voluntad. ¿Las enlazo con ese motivo?\n>\n> **Tú:** sí\n>\n> **Asistente:** enlazadas, motivo escrito en las dos. Te dejo el enlace para\n> abrirla en Obsidian: `obsidian://open?path=...`\n\nFíjate en el orden: el asistente propone, tú decides, y cada conexión queda\ncon su porqué escrito. Eso es todo el sistema.\n\n## Las tres carpetas\n\n```\ntu-vault/\n├── 40-Lecturas/     lo que entra: libros, artículos, vídeos, cursos\n├── 50-Notas/        lo que queda: ideas permanentes, tuyas, con tu título\n└── 60-Conceptos/    lo que conecta: cada tema es una nota real con backlinks\n```\n\nLa regla de oro: **nada entra suelto**. Cada idea se enlaza a su origen, a los\nconceptos que toca y, con moderación, a otras ideas. Y la moderación importa:\nmáximo 2-3 notas relacionadas, cada enlace con su porqué escrito. Un cajón con\ndoce enlaces no conecta nada; tres enlaces con motivo son un mapa.\n\n## Qué sabe hacer\n\n**Capturar.** `lectura_crear` abre la ficha de un libro o artículo;\n`lectura_nota` guarda apuntes mientras lees («cap 3: ...»); cuando una idea es\ntuya de verdad, `nota_permanente` la sube a `50-Notas/` con sus temas convertidos\nen conceptos navegables. `nota_enlazar` une dos ideas y deja escrito *por qué*.\n\n**Pensar.** `resurgir` es el corazón: le das un texto (una tarea, una duda, una\nidea a medias) y te devuelve las notas más conectadas con él. Solo aparece cuando\nhay solape real; si no hay nada, no inventa. `vault_buscar` es el grep de toda la\nvida, acotado para no inundar (20 resultados y te avisa si hubo más).\n\n**Podar.** Los grafos se pudren en silencio. `jardin` te enseña las notas\nhuérfanas, los enlaces rotos, los conceptos que nadie definió, las notas\nsobreconectadas y los conceptos duplicados («Hábito» y «Habitos» partiendo los\nbacklinks en dos). `concepto_fusionar` cose los nodos partidos.\n\n**Taller por proyecto.** Cualquier repo puede tener su `brain/` local con\napuntes crudos (`mini_nota`). `mini_listar` te dice cuáles se han ganado subir a\nla biblioteca (resuenan fuerte con lo que ya tienes, o llevan una semana\nmadurando) y `mini_promover` los sube. Taller abajo, biblioteca arriba: y\npromover siempre es decisión tuya.\n\n## La ingesta: un solo gesto\n\nNo hace falta que te aprendas las tools. Dile a tu asistente:\n\n> «añade esto **directo** a mi second brain»\n> «añade **lo más importante** de esto»\n> «apunta esto que estoy escribiendo»\n\ny la ingesta se dispara según toque. El servidor trae el procedimiento escrito\n(prompt MCP `ingerir`; en Claude Code aparece como comando\n`/mcp__second-brain__ingerir`): clasifica el texto (¿lectura con fuente, idea\ntuya, apunte de taller?), aplica el modo (`directo` guarda íntegro, `destilar`\nextrae las 1-3 ideas fuertes *en tus palabras* y te las enseña antes de crear\nnada, `auto` decide y te lo dice), identifica 2-4 conceptos (prefiriendo los\nque ya existen en tu grafo antes que inventar sinónimos), y teje. Las decisiones\nson tuyas y están marcadas como tales: qué ideas entran y qué conexiones se\ncrean. Vale para un párrafo pegado, un capítulo, o ese documento de Word que\nestás escribiendo: pégalo o pásale el fichero.\n\n## Leer notas: resources\n\nCada nota del grafo es también un **resource MCP**, así que leerla entera no\ngasta una tool call (y en Claude Code puedes adjuntarla con `@`):\n\n```\nvault://lectura/{titulo}\nvault://nota/{titulo}\nvault://concepto/{nombre}\n```\n\nEl patrón que funciona: buscar barato (`vault_buscar`, `resurgir`), leer entero\nsolo lo que interesa (el resource).\n\n## ¿Y si no uso Claude?\n\nFunciona igual, porque esto es MCP estándar y el protocolo ya lo habla casi\ntodo el mundo. La escalera completa, de más cómodo a más independiente:\n\n1. **Claude Desktop**: la vía del doble clic con el `.mcpb`. La única sin tocar\n   nada.\n2. **Cualquier otro cliente MCP** (ChatGPT de escritorio, Cursor, VS Code,\n   Windsurf, Zed, Gemini CLI...): usa el bloque de configuración JSON de arriba,\n   que es el mismo para todos.\n3. **Sin cuenta de nada y sin internet**: LM Studio soporta MCP con modelos\n   locales, así que tu second brain puede hablar con un modelo que corre en tu\n   propio ordenador y tus notas no salen de tu disco jamás.\n4. **Sin ninguna IA**: el vault son ficheros Markdown normales con wikilinks\n   normales. Con Obsidian a secas ya tienes un second brain manual perfectamente\n   usable; el servidor es el copiloto que captura, destila y te trae las ideas\n   de vuelta, pero tus notas nunca son rehenes de nadie.\n\n## Cómo se lleva con Obsidian\n\nEs su casa. Todo es Markdown plano con wikilinks nativos: graph view, backlinks\ny hover preview funcionan sin plugins. El servidor relee siempre (nunca cachea)\ny escribe de forma atómica, así que puedes editar en Obsidian con el servidor\ncorriendo sin que se pisen. El `jardin` juzga los enlaces como Obsidian: sin\ndistinguir mayúsculas.\n\nDos detalles útiles:\n\n- Cada nota creada devuelve su `ruta` en disco —que sirve siempre— y un enlace\n  `abrir` (`obsidian://open?path=...`): un clic y estás en la nota dentro de la\n  app, si la tienes. Va por ruta absoluta, así que da igual cómo hayas llamado a\n  tu vault o que apuntes a una subcarpeta suya.\n- `temas` y `relacionadas` viven en las propiedades (frontmatter). Obsidian los\n  trata como enlaces reales, pero para verlos en el graph view activa\n  «Propiedades» en los ajustes del grafo.\n\n> **¿Y Notion?** No. Este servidor trabaja sobre ficheros Markdown locales. Esa\n> es la gracia: tus datos son tuyos, se abren con cualquier editor y el grafo va\n> a la velocidad del disco, no de una API. Obsidian tampoco es obligatorio (vale\n> cualquier carpeta `.md`); es solo el mejor visor. Si vienes de Notion: exporta\n> tus notas como Markdown y suéltalas en el vault, y eso sí funciona.\n\n## Modo lexico y modo rag\n\n`resurgir` tiene dos motores, y el sistema te dice cuándo cambiar:\n\n- **`lexico`** (por defecto): puntúa coincidencias donde más significan:\n  título ×3, temas ×2, cuerpo ×1. Directo y transparente; con un brain pequeño\n  o mediano es todo lo que necesitas.\n- **`rag`**: BM25 por *fragmentos* con stemming castellano: «hábito» encuentra\n  «hábitos», y en vez de decirte solo *qué* nota conecta, te devuelve **el\n  párrafo exacto que responde**, listo para usar como contexto. Pensado para\n  cuando el brain crece y las notas son largas.\n\n¿Cuál usar? No lo pienses: empieza en `lexico` y deja que el sistema te guíe.\nLa sugerencia de pasar a rag aparece **solo cuando toca**, cuando se dan las\ndos cosas a la vez:\n\n1. tu brain ya es un puñado grande de notas (50+, configurable con\n   `BRAIN_RAG_UMBRAL`), **y**\n2. la búsqueda que acabas de hacer volvió floja en léxico (sin resultados o por\n   debajo del listón de conexión fuerte); es decir, justo el momento en que el\n   rag habría ayudado.\n\nY una sola vez por sesión: te lo dice, te explica el porqué, y no vuelve a\ninsistir. Si el léxico encuentra fuerte, no te interrumpe nadie. Probar es\ngratis: repite la consulta con `modo: \"rag\"` y compara; si convence, se fija\ncon `BRAIN_MODO=rag`. Sin índices que reconstruir ni modelos que descargar:\nlos dos motores releen el vault al vuelo, así que puedes seguir editando en\nObsidian sin miedo.\n\n## Los principios (por si te preguntas por qué es así)\n\n- **La escasez es el significado.** Las sugerencias de conexión solo aparecen\n  cuando son fuertes (y como mucho dos). Enlazarlo todo con todo es lo mismo que\n  no enlazar nada.\n- **Enlazar es decisión tuya.** El sistema sugiere; tú decides. Ninguna conexión\n  se crea como efecto secundario.\n- **El vault manda.** El servidor relee siempre y no cachea: edita a mano, usa\n  Obsidian, sincroniza con lo que quieras. Escritura atómica y frontmatter\n  editado línea a línea: tu formato no se toca.\n- **El contexto se paga.** Respuestas en JSON compacto, búsquedas acotadas,\n  diagnósticos con techo. Las tools de solo lectura van marcadas (`readOnlyHint`)\n  y la única destructiva (`concepto_fusionar`) también, para que tu cliente pida\n  confirmación donde toca.\n\n## Desarrollo\n\n```bash\nnpm install\nnpm test\n```\n\n## Licencia\n\nMIT. Úsalo, cámbialo, hazlo tuyo.\n",
  "bytes": 16248,
  "sha": "744d96d2a93eb57aa6c95c5fa570296c226677dadc281ed7c02ff6f87aca2d9b",
  "repo_slug": "portaltocoding/second-brain-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_portaltocoding_second_brain_mc_99018460/readme"
}