Joplin MCP Server

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

Quick Start

Install via npx (no installation required):

Configuration

Create a .env file with the following variables:

You can find your Joplin token in the Joplin desktop app under: Tools > Options > Web Clipper

WSL (Windows Subsystem for Linux) Setup

If you're running the MCP server in WSL and Joplin on Windows, you'll need to set up port forwarding because Joplin binds to 127.0.0.1 (localhost only) by default.

Option 1: Windows Port Forwarding (Recommended)

This is the simplest solution that requires no Joplin configuration changes and persists across reboots.

On Windows (PowerShell as Administrator):

Configure your .env file in WSL:

To find your Windows IP address:

To remove the port forward later (if needed):

Note: This port forwarding rule persists across reboots - you only need to set it up once!

Option 2: Configure Joplin to Listen on All Interfaces (Alternative)

If you prefer to configure Joplin directly instead of using port forwarding:

1. Find your Joplin configuration file:

   • Windows: C:\Users\YourUsername\.config\joplin-desktop\settings.json

2. Add this configuration to settings.json:

   { "clipperServer.host": "0.0.0.0" }

3. Restart Joplin for the changes to take effect

4. Set your .env file in WSL:

   JOPLIN_HOST=10.255.255.254 # WSL bridge IP from /etc/resolv.conf JOPLIN_PORT=41184 JOPLIN_TOKEN=your_joplin_token

Security Note: This makes Joplin accessible on your entire local network. The API token is still required for all operations.

Troubleshooting WSL Connectivity

Test connectivity from WSL:

Common issues:

• Connection refused: Port forwarding not set up or Joplin not running

  • Verify port forward: netsh interface portproxy show all (on Windows)

  • Verify Joplin is running with Web Clipper enabled

• Connection timeout: Windows Firewall is blocking the port

  • Open Windows Defender Firewall

  • Add Inbound Rule for TCP port 41184

• Wrong IP: Make sure you're using your actual Windows IP address

  • Check with ipconfig on Windows (look for IPv4 Address on your active network adapter)

Command Line Options

Command Line Usage Examples

MCP Client Configuration

Claude Desktop Configuration

Important: Claude Desktop does NOT support environment variable expansion (${VAR} syntax). You must provide values directly.

Option 1: Using env Section (Recommended)

Add to your claude_desktop_config.json:

Option 2: Using Command-Line Arguments

Restart Claude Desktop after updating the configuration.

Claude Code Configuration

Claude Code supports environment variable expansion in .mcp.json.

1. Set environment variables in your shell (add to ~/.bashrc or ~/.zshrc):

2. Use the included :

The repository includes a working .mcp.json file that uses environment variable expansion:

The server will automatically use JOPLIN_PORT and JOPLIN_HOST from your shell environment, or use the defaults (127.0.0.1:41184).

Other MCP Clients (Cursor, etc.)

Most MCP clients support environment variable expansion (${VAR} syntax).

With environment variables:

With direct values:

Using environment file:

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:

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.

search_notes

Searches for notes in Joplin and returns matching notebooks.

Parameters:

• query: The search query string

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

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

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

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

Testing Local Changes

License

MIT