This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin.
npm installCreate a .env file with the following variables:
JOPLIN_PORT=41184
JOPLIN_TOKEN=your_joplin_token
You can find your Joplin token in the Joplin desktop app under: Tools > Options > Web Clipper
Start the server:
npm startYou can also specify a custom environment file:
npm start -- --env-file .env.customUsage in Augment Code:
name: joplin
command: node /path/to/your/mcp-joplin/index.js --env-file /path/to/your/mcp-joplin/.env
Usage in mcp.json (cursor other tools)
"joplin":{
"command":"node",
"args":[
"/path/to/your/mcp-joplin/index.js",
"--env-file",
"/path/to/your/mcp-joplin/.env"
]
}The server logs all incoming commands and outgoing responses. Logs are stored in two places:
- Console output: Basic information is displayed in the console
- Log files: Detailed logs are saved in the
logsdirectory with timestamps
You can adjust the log level by setting the LOG_LEVEL environment variable:
LOG_LEVEL=debug npm startAvailable log levels (from most to least verbose):
debug: All messages including detailed command and response datainfo: Standard operational messages (default)warn: Warnings and errors onlyerror: Only error messages
Retrieves the complete notebook hierarchy from Joplin.
# Example output:
Notebook 1 (id: "abc123")
Subnotebook 1.1 (id: "def456")
Subnotebook 1.2 (id: "ghi789")
Notebook 2 (id: "jkl012")
Searches for notes in Joplin and returns matching notebooks.
Parameters:
query: The search query string
# Example usage:
search_notes query="project meeting"
# Example output:
Found 2 notes matching query: "project meeting"
NOTE: To read a notebook, use the notebook ID (not the note title)
- Note: "Weekly Project Meeting" (note_id: "abc123")
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Updated: 3/15/2025, 10:30:45 AM
Snippet: Notes from our weekly project meeting. Topics discussed: timeline, resources, next steps...
To read this notebook: read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
- Note: "Project Kickoff Meeting" (note_id: "def456")
Notebook: "Projects" (notebook_id: "72b1c45d89ef3212a67b98f4e5d23a1b")
Updated: 3/10/2025, 2:15:30 PM
Snippet: Initial project meeting with stakeholders. Key decisions: project scope, team members...
To read this notebook: read_notebook notebook_id="72b1c45d89ef3212a67b98f4e5d23a1b"
Important: Note the difference between note titles and IDs. When using the
read_notebookcommand, you must use the notebook ID (a long alphanumeric string), not the notebook title.
Reads the contents of a specific notebook.
Parameters:
notebook_id: The ID of the notebook to read
# Example usage:
read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
# Example output:
# Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Contains 3 notes:
NOTE: This is showing the contents of notebook "Work", not a specific note.
- Note: "Weekly Project Meeting" (note_id: "def456")
Updated: 3/15/2025, 10:30:45 AM
- ✅ Note: "Call client" (note_id: "ghi789")
Updated: 3/14/2025, 3:45:12 PM
- ☐ Note: "Prepare presentation" (note_id: "jkl012")
Updated: 3/13/2025, 9:20:33 AM
Common Error: If you try to use a note title (like "todo") instead of a notebook ID, you'll get an error. Always use the notebook ID (the long alphanumeric string) shown in the search results or notebook list.
Reads the full content of a specific note.
Parameters:
note_id: The ID of the note to read
# Example usage:
read_note note_id="def456"
# Example output:
# Note: "Weekly Project Meeting"
Note ID: def456
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Created: 3/15/2025, 10:00:12 AM
Updated: 3/15/2025, 10:30:45 AM
---
# Weekly Project Meeting
## Agenda
1. Project status update
2. Timeline review
3. Resource allocation
4. Next steps
## Notes
- Project is on track for Q2 delivery
- Need to allocate additional resources to the UI team
- Next meeting scheduled for next Friday
---
Related commands:
- To view the notebook containing this note: read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
- To search for more notes: search_notes query="your search term"
Note: The
read_notecommand shows the full content of a specific note, while theread_notebookcommand shows a list of notes in a notebook. Usesearch_notesto find notes and get their IDs.
Reads the full content of multiple notes at once.
Parameters:
note_ids: An array of note IDs to read
# Example usage:
read_multinote note_ids=["def456", "ghi789", "jkl012"]
# Example output:
# Reading 3 notes
## Note 1 of 3 (ID: def456)
### Note: "Weekly Project Meeting"
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Created: 3/15/2025, 10:00:12 AM
Updated: 3/15/2025, 10:30:45 AM
---
# Weekly Project Meeting
## Agenda
1. Project status update
2. Timeline review
---
## Note 2 of 3 (ID: ghi789)
### Note: "Call client"
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Status: Completed
Created: 3/14/2025, 3:00:00 PM
Updated: 3/14/2025, 3:45:12 PM
---
Discussed project timeline and next steps.
Client is happy with progress.
---
## Note 3 of 3 (ID: jkl012)
### Note: "Prepare presentation"
Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
Status: Not completed
Due: 3/20/2025, 9:00:00 AM
Created: 3/13/2025, 9:00:00 AM
Updated: 3/13/2025, 9:20:33 AM
---
# Presentation Outline
- Introduction
- Project overview
- Timeline
- Budget
- Next steps
---
# Summary
Total notes requested: 3
Successfully retrieved: 3
Tip: When you search for notes or view a notebook, you'll see a suggestion for using
read_multinotewith the exact IDs of the notes found. This makes it easy to read multiple related notes at once.
Create a .env.test.local file with your test configuration, then run:
npm testMIT