jordanburke/joplin-mcp-server

Joplin MCP Server

This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin.

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

Usage

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

Available Tools

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

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.

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"

Note: 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

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.

Development

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

MIT