Joplin MCP Server

Un servidor del Protocolo de Contexto de Modelo (MCP) para https://joplinapp.org/ que permite el acceso a notas a través de https://modelcontextprotocol.io. Perfecto para la integración con asistentes de IA como Claude.

GitHub
87
Prueba este MCPPatrocinado

Documentación

📝 Joplin MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) para Joplin que permite el acceso a notas a través del Protocolo de Contexto de Modelo. Perfecto para la integración con asistentes de IA como Claude.

✨ Características

  • 🔍 Buscar notas: Búsqueda de texto completo en todas las notas
  • 📚 Listar cuadernos: Explorar cuadernos y subcuadernos disponibles
  • 🗂️ Crear cuadernos: Crear cuadernos y subcuadernos anidados
  • 📖 Leer notas: Recuperar notas individuales
  • ✏️ Editar notas: Crear nuevas notas y actualizar las existentes
  • 🗑️ Eliminar notas: Mover notas a la papelera o eliminarlas permanentemente
  • 📥 Importar Markdown: Importar archivos Markdown como notas
  • 🤖 Integración con IA: Integración perfecta con Claude y otros asistentes de IA compatibles con MCP

🚀 Instalación

Requisitos previos

  • Python 3.10 o superior
  • Joplin Desktop con el Servicio Web Clipper habilitado
  • uv (gestor de paquetes de Python)
# Clone repository
git clone https://github.com/dweigend/joplin-mcp.git
cd joplin-mcp

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
```bash
uv pip install -e .

⚙️ Configuración

Token de API de Joplin

  1. Abre Joplin Desktop
  2. Ve a Herramientas -> Opciones -> Web Clipper
  3. Habilita el Servicio Web Clipper
  4. Copia el Token de API

Crea un archivo .env en el directorio del proyecto:

JOPLIN_TOKEN=your_api_token_here

Configuración de Claude Desktop

  1. Instalar Claude Desktop

    • Descarga Claude Desktop
    • Asegúrate de tener la última versión (Menú: Claude -> Buscar actualizaciones...)

  2. Configurar el servidor MCP

    {
  "mcpServers": {
    "joplin": {
      "command": "/PATH/TO/UV/uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/PROJECT/joplin_mcp",
        "run",
        "src/mcp/joplin_mcp.py"
      ]
    }
  }
}
    • Reemplaza /PATH/TO/UV/uv con la ruta absoluta a tu instalación de uv
      • Encuentra la ruta con: which uv
      • Ejemplo macOS: /Users/username/.local/bin/uv
      • Ejemplo Windows: C:\Users\username\AppData\Local\Microsoft\WindowsApps\uv.exe
    • Reemplaza /PATH/TO/YOUR/PROJECT/joplin_mcp con la ruta absoluta a tu proyecto

    Importante: Claude Desktop necesita la ruta completa a uv ya que no puede acceder a las variables de entorno del shell.

🛠️ Herramientas disponibles

search_notes

Busca notas en Joplin.

Parámetros:

  • query (cadena): Consulta de búsqueda
  • limit (entero, opcional): Número máximo de resultados (por defecto: 100)

get_note

Recupera una nota específica por su ID.

Parámetros:

  • note_id (cadena): ID de la nota

list_notebooks

Lista todos los cuadernos disponibles como un árbol.

Parámetros:

  • Ninguno

create_notebook

Crea un nuevo cuaderno.

Parámetros:

  • title (cadena): Título del cuaderno
  • parent_id (cadena, opcional): ID del cuaderno padre
  • parent_notebook_name (cadena, opcional): Título del cuaderno padre o ruta completa

create_note

Crea una nueva nota.

Parámetros:

  • title (cadena): Título de la nota
  • body (cadena, opcional): Contenido de la nota en Markdown
  • parent_id (cadena, opcional): ID de la carpeta padre
  • notebook_name (cadena, opcional): Título del cuaderno o ruta completa como Work/Projects
  • is_todo (booleano, opcional): Si es un elemento de tarea pendiente

update_note

Actualiza una nota existente.

Parámetros:

  • note_id (cadena): ID de la nota a actualizar
  • title (cadena, opcional): Nuevo título
  • body (cadena, opcional): Nuevo contenido
  • parent_id (cadena, opcional): Nuevo ID de carpeta padre
  • notebook_name (cadena, opcional): Nuevo título de cuaderno o ruta completa como Work/Projects
  • is_todo (booleano, opcional): Nuevo estado de tarea pendiente

delete_note

Elimina una nota.

Parámetros:

  • note_id (cadena): ID de la nota a eliminar
  • permanent (booleano, opcional): Si es verdadero, elimina la nota permanentemente

import_markdown

Importa un archivo Markdown como una nueva nota.

Parámetros:

  • file_path (cadena): Ruta al archivo Markdown
  • parent_id (cadena, opcional): ID de la carpeta padre
  • notebook_name (cadena, opcional): Título del cuaderno o ruta completa como Work/Projects

🧪 Desarrollo

Modo de depuración

Para iniciar el servidor en modo de depuración:

MCP_LOG_LEVEL=debug mcp dev src/mcp/joplin_mcp.py

Esto inicia el Inspector MCP en http://localhost:5173 donde puedes probar las herramientas.

📄 Licencia

Licencia MIT - Copyright (c) 2025 David Weigend

👤 Autor

David Weigend

🤝 Contribuciones

¡Las contribuciones, problemas y solicitudes de funciones son bienvenidos! Visita la página de problemas.