Joplin MCP Server

🚀 Joplin MCP Server

This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin, which provides a convenient way to interact with Joplin's data.

🚀 Quick Start

Prerequisites

Before starting, make sure you have Node.js and npm installed on your system.

Installation

npm install

Configuration

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

Starting the Server

Local Development

Start the server:

npm start

You can also specify a custom environment file:

npm start -- --env-file .env.custom

Using npx (Recommended)

After publishing to npm, you can use npx to run the server without installation:

# Using command line arguments
npx joplin-mcp-server --port 41184 --token your_joplin_token

# Using environment file
npx joplin-mcp-server --env-file /path/to/your/.env

# Mixed approach (args override env file)
npx joplin-mcp-server --env-file .env --port 41185

Command Line Options

OPTIONS:
  --env-file <file>    Load environment variables from file
  --port <port>        Joplin port (default: 41184)
  --token <token>      Joplin API token
  --help, -h           Show help message

MCP Client Configuration

Usage in Augment Code

name: joplin
command: npx joplin-mcp-server --port 41184 --token your_token

Usage in mcp.json (Cursor and other tools)

{
  "joplin": {
    "command": "npx",
    "args": ["joplin-mcp-server", "--port", "41184", "--token", "your_joplin_token"]
  }
}

Or using environment file:

{
  "joplin": {
    "command": "npx",
    "args": ["joplin-mcp-server", "--env-file", "/path/to/your/.env"]
  }
}

Legacy Usage (if installed locally)

Usage 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"
      ]
  }

Logging

The server logs all incoming commands and outgoing responses. Logs are stored in two places:

1. Console output: Basic information is displayed in the console
2. Log files: Detailed logs are saved in the logs directory with timestamps

You can adjust the log level by setting the LOG_LEVEL environment variable:

LOG_LEVEL=debug npm start

Available log levels (from most to least verbose):

• debug: All messages including detailed command and response data
• info: Standard operational messages (default)
• warn: Warnings and errors only
• error: Only error messages

✨ Features

list_notebooks

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")

search_notes

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

Note the difference between note titles and IDs. When using the read_notebook command, you must use the notebook ID (a long alphanumeric string), not the notebook title.

read_notebook

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

⚠️ Important Note

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.

read_note

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"

💡 Usage Tip

The read_note command shows the full content of a specific note, while the read_notebook command shows a list of notes in a notebook. Use search_notes to find notes and get their IDs.

read_multinote

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

💡 Usage Tip

When you search for notes or view a notebook, you'll see a suggestion for using read_multinote with the exact IDs of the notes found. This makes it easy to read multiple related notes at once.

🔧 Technical Details

Local Development Setup

To test the npx command locally during development:

# In the project root directory
cd /path/to/mcp-joplin
npm install
npm link

After linking, you can test your local changes immediately:

# Test the CLI
npx joplin-mcp-server --help
npx joplin-mcp-server --port 41184 --token your_token

# Make code changes, then test again (no rebuild needed)
npx joplin-mcp-server --help

Making Changes

1. Edit any .js files in the project
2. Run tests: npm test
3. Test the CLI: npx joplin-mcp-server --help

No build step is required - changes are immediately available through the npm link.

Running Tests

Create a .env.test.local file with your test configuration, then run:

npm test

Publishing to npm

To make this package available via npx:

1. Update the version in package.json
2. Run npm publish

Users can then run it with npx joplin-mcp-server

Unlinking (if needed)

To remove the local link:

npm unlink -g joplin-mcp-server

📄 License

This project is licensed under the MIT license.