Joplin MCP Server

📝 Joplin MCP Server

Um servidor Model Context Protocol (MCP) para Joplin que permite acesso a notas através do Model Context Protocol. Perfeito para integração com assistentes de IA como o Claude.

✨ Recursos

• 🔍 Pesquisar Notas: Pesquisa de texto completo em todas as notas
• 📚 Listar Cadernos: Navegue pelos cadernos e subcadernos disponíveis
• 🗂️ Criar Cadernos: Crie cadernos e subcadernos aninhados
• 📖 Ler Notas: Recupere notas individuais
• ✏️ Editar Notas: Crie novas notas e atualize as existentes
• 🗑️ Excluir Notas: Mova notas para a lixeira ou exclua permanentemente
• 📥 Importação Markdown: Importe arquivos markdown como notas
• 🤖 Integração com IA: Integração perfeita com o Claude e outros assistentes de IA compatíveis com MCP

🚀 Instalação

Pré-requisitos

• Python 3.10 ou superior
• Joplin Desktop com o Serviço Web Clipper habilitado
• uv (gerenciador de pacotes 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 .

⚙️ Configuração

Token da API do Joplin

1. Abra o Joplin Desktop
2. Vá em Ferramentas -> Opções -> Web Clipper
3. Habilite o Serviço Web Clipper
4. Copie o Token da API

Crie um arquivo .env no diretório do projeto:

JOPLIN_TOKEN=your_api_token_here

Configuração do Claude Desktop

1. Instale o Claude Desktop

   • Baixe o Claude Desktop
   • Certifique-se de ter a versão mais recente (Menu: Claude -> Verificar atualizações...)

2. Configure o Servidor MCP

   {
     "mcpServers": {
       "joplin": {
         "command": "/PATH/TO/UV/uv",
         "args": [
           "--directory",
           "/PATH/TO/YOUR/PROJECT/joplin_mcp",
           "run",
           "src/mcp/joplin_mcp.py"
         ]
       }
     }
   }
   

   • Substitua /PATH/TO/UV/uv pelo caminho absoluto da sua instalação do uv
     • Encontre o caminho com: which uv
     • Exemplo macOS: /Users/username/.local/bin/uv
     • Exemplo Windows: C:\Users\username\AppData\Local\Microsoft\WindowsApps\uv.exe
   • Substitua /PATH/TO/YOUR/PROJECT/joplin_mcp pelo caminho absoluto do seu projeto

   Importante: O Claude Desktop precisa do caminho completo para uv, pois não consegue acessar variáveis de ambiente do shell.

🛠️ Ferramentas Disponíveis

search_notes

Pesquisa notas no Joplin.

Parâmetros:

• query (string): Consulta de pesquisa
• limit (int, opcional): Número máximo de resultados (padrão: 100)

get_note

Recupera uma nota específica pelo seu ID.

Parâmetros:

• note_id (string): ID da nota

list_notebooks

Lista todos os cadernos disponíveis como uma árvore.

Parâmetros:

• Nenhum

create_notebook

Cria um novo caderno.

Parâmetros:

• title (string): Título do caderno
• parent_id (string, opcional): ID do caderno pai
• parent_notebook_name (string, opcional): Título do caderno pai ou caminho completo

create_note

Cria uma nova nota.

Parâmetros:

• title (string): Título da nota
• body (string, opcional): Conteúdo da nota em Markdown
• parent_id (string, opcional): ID da pasta pai
• notebook_name (string, opcional): Título do caderno ou caminho completo como Work/Projects
• is_todo (boolean, opcional): Se é um item de tarefa

update_note

Atualiza uma nota existente.

Parâmetros:

• note_id (string): ID da nota a ser atualizada
• title (string, opcional): Novo título
• body (string, opcional): Novo conteúdo
• parent_id (string, opcional): Novo ID da pasta pai
• notebook_name (string, opcional): Novo título do caderno ou caminho completo como Work/Projects
• is_todo (boolean, opcional): Novo status de tarefa

delete_note

Exclui uma nota.

Parâmetros:

• note_id (string): ID da nota a ser excluída
• permanent (boolean, opcional): Se verdadeiro, exclui a nota permanentemente

import_markdown

Importa um arquivo markdown como uma nova nota.

Parâmetros:

• file_path (string): Caminho para o arquivo markdown
• parent_id (string, opcional): ID da pasta pai
• notebook_name (string, opcional): Título do caderno ou caminho completo como Work/Projects

🧪 Desenvolvimento

Modo de Depuração

Para iniciar o servidor em modo de depuração:

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

Isso inicia o MCP Inspector em http://localhost:5173 onde você pode testar as ferramentas.

📄 Licença

Licença MIT - Copyright (c) 2025 David Weigend

👤 Autor

David Weigend

• Site: weigend.studio
• GitHub: @dweigend

🤝 Contribuições

Contribuições, problemas e solicitações de recursos são bem-vindos! Visite a página de issues.