A Model Context Protocol (MCP) server for interacting with Joplin notes.
- create_notebook: Create notebooks directly from the MCP client
- create_note: Add new Markdown notes to a specific notebook
- update_note: Modify the title and/or body of an existing note
- delete_note: Remove notes (optionally permanently) by ID
- delete_notebook: Remove notebooks/folders (optionally permanently) by ID
- search_notes: Search notes by keyword across all notebooks
- read_note: Read full note content in Markdown format
- list_notebooks: List all notebooks (folders) in Joplin
📖 Complete installation guide: See INSTALL.md for detailed installation, configuration, and uninstallation instructions.
git clone <repository-url> joplin-mcp-macos
cd joplin-mcp-macos
./install.shThe automatic installer will detect your Joplin token, configure the environment, and validate the installation. For more options and manual configuration, consult INSTALL.md.
This fork is specifically optimised for macOS compatibility while maintaining Linux support.
- macOS 12.3+ (Monterey or later)
- Python 3.9+ (included with macOS 12.3+)
- Xcode Command Line Tools:
xcode-select --install
- ✅ Automatic Joplin detection at
~/Library/Application Support/Joplin/ - ✅ BSD-compatible commands (no GNU dependencies required)
- ✅ Native Python 3.9+ support
- ✅ Works with macOS-native tools (no Homebrew required)
| Feature | Linux (GNU) | macOS (BSD) |
|---|---|---|
| Python version detection | Uses GNU grep | Uses Python directly |
| Port checking | netstat -tuln |
netstat -an |
| Process detection | pgrep -f |
ps aux | grep |
| File operations | GNU find extensions | POSIX shell globs |
See MACOS.md for detailed compatibility analysis.
Search for notes by keyword.
Input: {"query": "search term"}
Example:
⚙ joplin_search_notes [query="AI"]
Result:
- Machine Learning Notes (ID: abc123)
- AI Research Paper (ID: def456)
Read the full content of a specific note.
Input: {"note_id": "note-id-here"}
Example:
⚙ joplin_read_note [note_id="abc123"]
Result:
# Machine Learning Notes
This is the markdown content of the note...
List all notebooks/folders in Joplin.
Example:
⚙ joplin_list_notebooks
Result:
- Work (ID: folder-abc)
- Personal (ID: folder-def)
- Research (ID: folder-ghi)
Create a new notebook in Joplin.
Input: {"title": "Projects"}
Example:
⚙ joplin_create_notebook [title="Projects"]
Result:
Libreta creada: Projects (ID: folder-xyz)
Create a new note inside an existing notebook.
Input: {"title": "Meeting Notes", "body": "# Agenda", "parent_id": "folder-xyz"}
Example:
⚙ joplin_create_note [title="Meeting Notes", parent_id="folder-xyz"]
Result:
Nota creada: Meeting Notes (ID: note-123)
Update the title and/or body of an existing note.
Input: {"note_id": "note-123", "title": "New Title"}
Example:
⚙ joplin_update_note [note_id="note-123", title="New Title"]
Result:
Nota actualizada (ID: note-123).
# Verify that the token works
curl "http://localhost:41184/notes?token=YOUR_TOKEN&limit=1"
# If it fails, reinstall with new token
./install.sh# Verify that Joplin responds
~/.joplin-mcp/joplin-mcp-doctor.sh
# Ensure that:
# 1. Joplin desktop is running
# 2. Web Clipper is enabled (Options > Web Clipper > Enable)
# 3. Port 41184 is available# Verify installation
~/.joplin-mcp/joplin-mcp-doctor.sh
# View logs
cat ~/.joplin-mcp/logs/install.log
# Reinstall if necessary
./install.shIf something goes wrong, you can restore the backup:
# View available backups
ls -la ~/.joplin-mcp/backup/
# Restore opencode configuration
cp ~/.joplin-mcp/backup/20250121_143022/opencode.json.backup ~/.config/opencode/opencode.json
# Or restore a JSONC config
cp ~/.joplin-mcp/backup/20250121_143022/opencode.jsonc.backup ~/.config/opencode/opencode.jsonc
# Or restore everything
rm -rf ~/.joplin-mcp
cp -r ~/.joplin-mcp-backup-20250121_143022 ~/.joplin-mcpjoplin-mcp-macos/
├── install.sh # Main installer
├── uninstall.sh # Uninstaller
├── joplin-mcp-doctor.sh # Diagnostic script
├── run_mcp.sh # Wrapper template
├── server.py # MCP server
├── requirements.txt # Python dependencies
├── mcp_config.json # Example for Claude Desktop
├── CHANGELOG.md # Change history
└── README.md # This file
# Manual server test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | ~/.joplin-mcp/run_mcp.sh
# Full diagnostic
~/.joplin-mcp/joplin-mcp-doctor.sh- Added MCP tools to create notebooks, create notes, and update existing note content
- Refined Joplin request helper to support POST/PUT operations with JSON payloads
- Updated the project version to 2.1 across scripts, server metadata, and documentation
- Refreshed repository references in the documentation for
joplin-mcp-macos
- Complete translation to British English
- Added project attribution (JoplinApp, OpenCode, MCP Protocol)
- Updated all version references to 1.3
- Security verification: no personal information leaks
- Fixed installation menu logic
- Fixed backup self-copy error
- Updated all version references to 1.2
- New: Automatic installer (
install.sh) - New: Uninstaller (
uninstall.sh) - New: Diagnostic script (
joplin-mcp-doctor.sh) - New: Automatic token detection from Joplin settings
- New: Token validation during installation
- New: Post-installation tests
- New: Automatic configuration backup
- New: Logging system
- Improvement: Idempotency on reinstallations
- Improvement: Error handling and recovery
- Initial stable release
- search_notes, read_note, list_notebooks tools
- Wrapper script support for OpenCode
- Environment variable configuration
- MCP protocol implementation
- Never commit your Joplin token to git
- The installer saves the token in
~/.joplin-mcp/run_mcp.sh(accessible only by your user) - The repository only contains placeholders (
TOKEN_JOPLIN) - Backups are saved in
~/.joplin-mcp/backup/(check permissions)
GPL v3 License - See LICENSE file for details
This project is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This project is built on the following technologies:
- JoplinApp - The open source note-taking application
- OpenCode - AI-powered code development framework
- MCP Protocol - Model Context Protocol version 2024-11-05
This project was developed with the assistance of:
- DeepSeek - AI model used for code development, architecture design, and documentation
- Kimi - AI model used for code review, optimisation, and testing
Special thanks to the open-source AI community for making tools like these accessible to developers.
Contributions are welcome! Please ensure:
- No tokens or sensitive data in commits
- Follow existing code style
- Update README.md if adding features
- Test with
./joplin-mcp-doctor.sh
For issues or questions:
- Run
~/.joplin-mcp/joplin-mcp-doctor.shfor diagnostics - Check logs:
~/.joplin-mcp/logs/install.log - Open an issue on GitHub