Servidor MCP de Joplin

Un servidor del Protocolo de Contexto de Modelo (MCP) que se integra con las notas de Joplin, permitiendo a los clientes de IA (como Perplexity) acceder y manipular tus cuadernos y notas a través de la API de Web Clipper de Joplin.

Características

🔍 Funcionalidad de búsqueda: Busca notas y cuadernos
📖 Lectura de contenido: Obtén el contenido completo de notas específicas
📝 Funciones de creación: Crea nuevas notas y cuadernos
✏️ Funciones de actualización/edición: Actualiza el contenido de las notas, añade contenido a las notas y cambia el nombre de los cuadernos
🗑️ Funciones de eliminación: Elimina notas y cuadernos (admite papelera o eliminación permanente)
🔄 Funcionalidad de movimiento: Mueve notas a diferentes cuadernos
📋 Funcionalidad de listado: Lista todos los cuadernos y las notas dentro de cuadernos específicos

Requisitos

Joplin Desktop - Asegúrate de que esté instalado y en ejecución
Node.js 18+ - Requerido para ejecutar el servidor MCP
Web Clipper habilitado - Habilita el servicio Web Clipper en Joplin

Instalación y configuración

1. Habilitar Joplin Web Clipper

Abre la aplicación de escritorio de Joplin
Ve a Herramientas → Opciones → Web Clipper
Marca Habilitar el servicio Web Clipper
Anota el número de puerto que se muestra (normalmente 41184)
Copia el token de API (si se requiere autenticación)

2. Instalar el servidor MCP de Joplin

# Clone or download this project
cd mcp-joplin

# Install dependencies
npm install

# Compile TypeScript
npm run build

3. Ejecución de prueba

# Run directly (will auto-detect Joplin service)
npm start

# Or specify port
npm start -- --port 41184

# Or specify token (if needed)
npm start -- --token YOUR_API_TOKEN

# View help
npm start -- --help

4. Usando npx

# Global installation (recommended)
npm install -g .

# Then use anywhere
npx mcp-joplin

# Or run locally
npx . --port 41184

Configuración del cliente MCP

Configurar Perplexity u otros clientes MCP

Añade la siguiente configuración al archivo de configuración de tu cliente MCP:

🔐 Configuración (Token de API requerido)

Este servidor MCP requiere un token de API de Joplin para funcionar correctamente:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

💡 Importante: El token de API es necesario para que este servidor MCP funcione correctamente.

Ejemplo de configuración de Claude Desktop

Configuración de Claude Desktop

En ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

Herramientas MCP disponibles

1. get_note_content

Obtén el contenido completo de una nota específica

Parameters: noteId (string) - The ID of the note

2. search_notes

Busca notas

Parameters:
- query (string) - Search keywords
- limit (number, optional) - Result limit (default: 20)

3. search_notebooks

Busca cuadernos

Parameters: query (string) - Search keywords

4. list_notebooks

Lista todos los cuadernos

Parameters: None

5. list_notes

Lista las notas en un cuaderno específico

Parameters:
- notebookId (string) - The ID of the notebook
- limit (number, optional) - Result limit (default: 50)

5.1. list_sub_notebooks

Lista los subcuadernos dentro de un cuaderno específico

Parameters:
- parentNotebookId (string) - The ID of the parent notebook

6. create_note

Crea una nueva nota

Parameters:
- title (string) - Note title
- body (string) - Note content (Markdown format)
- notebookId (string, optional) - Target notebook ID

7. create_notebook

Crea un nuevo cuaderno

Parameters:
- title (string) - Notebook title
- parentId (string, optional) - Parent notebook ID (for sub-notebooks)

8. delete_note

Elimina una nota

Parameters:
- noteId (string) - ID of the note to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

9. delete_notebook

Elimina un cuaderno

Parameters:
- notebookId (string) - ID of the notebook to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

10. move_note

Mueve una nota a un cuaderno diferente

Parameters:
- noteId (string) - ID of the note to move
- targetNotebookId (string) - Target notebook ID

11. update_note

Actualiza el título y/o el cuerpo de una nota existente

Parameters:
- noteId (string) - ID of the note to update
- title (string, optional) - New note title
- body (string, optional) - New note content (full replacement, not a patch)

Notas:

Se debe proporcionar al menos uno de los campos title o body
Úsalo al reemplazar el contenido de una nota o cambiar el nombre de una nota

12. append_to_note

Añade contenido al final de una nota existente

Parameters:
- noteId (string) - ID of the note to append to
- content (string) - Content to append
- separator (string, optional) - Separator inserted before appended content (default: "\n\n")

Notas:

Úsalo para registros, notas de reuniones, información complementaria o resultados de pruebas
Prefiere esto sobre update_note cuando la intención sea añadir contenido sin reemplazar el cuerpo existente

13. update_notebook

Actualiza el título de un cuaderno existente

Parameters:
- notebookId (string) - ID of the notebook to update
- title (string) - New notebook title

14. scan_unchecked_items

Escanea cuadernos y subcuadernos en busca de elementos de tareas pendientes sin completar (- [ ])

Parameters:
- notebookId (string) - ID of the notebook to scan
- includeSubNotebooks (boolean, optional) - Whether to recursively scan sub-notebooks (default: true)

Semántica de edición

Usa update_note para reemplazar el título y/o el cuerpo de una nota
Usa append_to_note para añadir contenido al final de una nota conservando el contenido existente
Usa move_note para cambiar a qué cuaderno pertenece una nota
Usa update_notebook para cambiar el nombre de un cuaderno

Ejemplos de uso

Ejemplos de conversación en clientes de IA:

You: "Search for notes containing 'Python'"
AI: Using search_notes tool to search for relevant notes...

You: "Create a new notebook called 'Learning Plan'"
AI: Using create_notebook tool to create a new notebook...

You: "Create a note about JavaScript in the Learning Plan notebook"
AI: Using list_notebooks to find the notebook ID, then using create_note to create the note...

You: "Show the complete content of a specific note"
AI: Using get_note_content tool to retrieve note content...

You: "Update the title of note abc123 to Weekly Review"
AI: Using update_note tool to rename the note...

You: "Append these test results to note abc123"
AI: Using append_to_note tool to add the new content to the end of the note...

You: "Rename notebook xyz789 to Project Archive"
AI: Using update_notebook tool to rename the notebook...

You: "Scan my project notebook for all uncompleted todo items"
AI: Using scan_unchecked_items tool to scan all sub-notebooks...

Solución de problemas

Problemas de conexión

Confirma que Joplin se está ejecutando
- La aplicación de escritorio de Joplin debe permanecer abierta
Comprueba la configuración de Web Clipper
- Asegúrate de que el servicio Web Clipper esté habilitado
- Comprueba la configuración del puerto (predeterminado 41184)

Ver mensajes de error

# Use verbose mode to see errors
DEBUG=* npm start

Errores comunes

"Joplin Web Clipper service not found": Asegúrate de que Joplin se esté ejecutando y que Web Clipper esté habilitado
"Connection refused": Comprueba si la configuración del puerto es correcta
"Unauthorized" o "403 Forbidden": Se requiere el token de API (consulta las instrucciones a continuación)

🔑 Token de API requerido

El token de API es necesario para que este servidor MCP funcione correctamente.

Obtener un token de API

En Joplin, ve a Herramientas → Opciones → Web Clipper
Copia el token que se muestra
Añade --token TU_TOKEN al comando de inicio

Desarrollo

# Run in development mode
npm run dev

# Compile
npm run build

# Prepare for publishing
npm run prepublishOnly

Arquitectura técnica

Lenguaje: TypeScript/Node.js
SDK de MCP: @modelcontextprotocol/sdk
Cliente HTTP: axios
CLI: commander
API: API de Joplin Web Clipper

Detalles técnicos

Búsqueda de cuadernos: Debido a las limitaciones en la API de búsqueda de Joplin para búsquedas de carpetas, utilizamos filtrado del lado del cliente para implementar la funcionalidad de búsqueda de cuadernos
Manejo de paginación: Maneja automáticamente el mecanismo de paginación de la API de Joplin (predeterminado 100 elementos por página), asegurando que se recuperen listas completas de cuadernos y notas, resolviendo el problema de la visualización incompleta de subcuadernos
Manejo de errores: Mecanismo completo de manejo de errores, incluidos los errores de la API de Joplin y los errores de conexión de red
Detección automática: Admite la detección automática del puerto de Joplin Web Clipper (41184-41194)

Licencia

Licencia MIT

Contribución

¡Los problemas y las solicitudes de extracción (Pull Requests) son bienvenidos!

Soporte

Si encuentras problemas, por favor:

Comprueba si Joplin Web Clipper se está ejecutando normalmente
Revisa los mensajes de error y los registros
Envía un problema (Issue) con información detallada del error