Skip to content
Back to search

joplin-mcp-server

A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dweigend--joplin-mcp-server/badge.svg)](/listings/dweigend--joplin-mcp-server)

HTML

<a href="/listings/dweigend--joplin-mcp-server"><img src="/api/listings/dweigend--joplin-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.10 or higher - [Joplin Desktop](https://joplinapp.org/) with Web Clipper Service enabled - [uv](https://github.com/astral-sh/uv) (Python package manager)

# 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 .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 173 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 📝 Joplin MCP Server
  2. A Model Context Protocol (MCP) Server for [Joplin](https://joplinapp.org/) that enables note access through the [Model Context Protocol](https://modelcontextprotocol.io). Perfect for integration with AI assistants like Claude.
  3. ## ✨ Features
  4. - 🔍 **Search Notes**: Full-text search across all notes
  5. - 📚 **List Notebooks**: Browse available notebooks and sub-notebooks
  6. - 🗂️ **Create Notebooks**: Create notebooks and nested sub-notebooks
  7. - 📖 **Read Notes**: Retrieve individual notes
  8. - ✏️ **Edit Notes**: Create new notes and update existing ones
  9. - 🗑️ **Delete Notes**: Move notes to trash or delete permanently
  10. - 📥 **Markdown Import**: Import markdown files as notes
  11. - 🤖 **AI Integration**: Seamless integration with Claude and other MCP-capable AI assistants
  12. ## 🚀 Installation
  13. ### Prerequisites
  14. - Python 3.10 or higher
  15. - [Joplin Desktop](https://joplinapp.org/) with Web Clipper Service enabled
  16. - [uv](https://github.com/astral-sh/uv) (Python package manager)
  17. ```bash
  18. # Clone repository
  19. git clone https://github.com/dweigend/joplin-mcp.git
  20. cd joplin-mcp
  21. # Create and activate virtual environment
  22. uv venv
  23. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  24. # Install dependencies
  25. ```bash
  26. uv pip install -e .
  27. ```
  28. ## ⚙️ Configuration
  29. ### Joplin API Token
  30. 1. Open Joplin Desktop
  31. 2. Go to Tools -> Options -> Web Clipper
  32. 3. Enable the Web Clipper Service
  33. 4. Copy the API Token
  34. Create a `.env` file in the project directory:
  35. ```bash
  36. JOPLIN_TOKEN=your_api_token_here
  37. ```
  38. ### Claude Desktop Setup
  39. 1. **Install Claude Desktop**
  40. - Download [Claude Desktop](https://claude.ai/download)
  41. - Ensure you have the latest version (Menu: Claude -> Check for Updates...)
  42. 2. **Configure MCP Server**
  43. ```json
  44. {
  45. "mcpServers": {
  46. "joplin": {
  47. "command": "/PATH/TO/UV/uv",
  48. "args": [
  49. "--directory",
  50. "/PATH/TO/YOUR/PROJECT/joplin_mcp",
  51. "run",
  52. "src/mcp/joplin_mcp.py"
  53. ]
  54. }
  55. }
  56. }
  57. ```
  58. - Replace `/PATH/TO/UV/uv` with the absolute path to your uv installation
  59. - Find the path with: `which uv`
  60. - Example macOS: `/Users/username/.local/bin/uv`
  61. - Example Windows: `C:\Users\username\AppData\Local\Microsoft\WindowsApps\uv.exe`
  62. - Replace `/PATH/TO/YOUR/PROJECT/joplin_mcp` with the absolute path to your project
  63. **Important**: Claude Desktop needs the full path to `uv` as it cannot access shell environment variables.
  64. ## 🛠️ Available Tools
  65. ### search_notes
  66. Search for notes in Joplin.
  67. **Parameters:**
  68. - `query` (string): Search query
  69. - `limit` (int, optional): Maximum number of results (default: 100)
  70. ### get_note
  71. Retrieve a specific note by its ID.
  72. **Parameters:**
  73. - `note_id` (string): ID of the note
  74. ### list_notebooks
  75. List all available notebooks as a tree.
  76. **Parameters:**
  77. - None
  78. ### create_notebook
  79. Create a new notebook.
  80. **Parameters:**
  81. - `title` (string): Notebook title
  82. - `parent_id` (string, optional): Parent notebook ID
  83. - `parent_notebook_name` (string, optional): Parent notebook title or full path
  84. ### create_note
  85. Create a new note.
  86. **Parameters:**
  87. - `title` (string): Note title
  88. - `body` (string, optional): Note content in Markdown
  89. - `parent_id` (string, optional): ID of parent folder
  90. - `notebook_name` (string, optional): Notebook title or full path such as `Work/Projects`
  91. - `is_todo` (boolean, optional): Whether this is a todo item
  92. ### update_note
  93. Update an existing note.
  94. **Parameters:**
  95. - `note_id` (string): ID of note to update
  96. - `title` (string, optional): New title
  97. - `body` (string, optional): New content
  98. - `parent_id` (string, optional): New parent folder ID
  99. - `notebook_name` (string, optional): New notebook title or full path such as `Work/Projects`
  100. - `is_todo` (boolean, optional): New todo status
  101. ### delete_note
  102. Delete a note.
  103. **Parameters:**
  104. - `note_id` (string): ID of note to delete
  105. - `permanent` (boolean, optional): If true, permanently delete the note
  106. ### import_markdown
  107. Import a markdown file as a new note.
  108. **Parameters:**
  109. - `file_path` (string): Path to the markdown file
  110. - `parent_id` (string, optional): ID of parent folder
  111. - `notebook_name` (string, optional): Notebook title or full path such as `Work/Projects`
  112. ## 🧪 Development
  113. ### Debug Mode
  114. To start the server in debug mode:
  115. ```bash
  116. MCP_LOG_LEVEL=debug mcp dev src/mcp/joplin_mcp.py
  117. ```
  118. This starts the MCP Inspector at http://localhost:5173 where you can test the tools.
  119. ## 📄 License
  120. [MIT License](LICENSE) - Copyright (c) 2025 David Weigend
  121. ## 👤 Author
  122. **David Weigend**
  123. * Website: [weigend.studio](https://weigend.studio)
  124. * GitHub: [@dweigend](https://github.com/dweigend)
  125. ## 🤝 Contributing
  126. Contributions, issues and feature requests are welcome!
  127. Visit the [issues page](https://github.com/dweigend/joplin-mcp/issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.