npm - joplin-mcp-server - Versions diffs - 1.3.0 → 2.0.1 - Mend

joplin-mcp-server 1.3.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,520 +1,278 @@
 # Joplin MCP Server
-This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin.
+[![npm version](https://img.shields.io/npm/v/joplin-mcp-server)](https://www.npmjs.com/package/joplin-mcp-server)
+[![CI](https://github.com/jordanburke/joplin-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/jordanburke/joplin-mcp-server/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-## Quick Start
+A self-contained MCP (Model Context Protocol) server for [Joplin](https://joplinapp.org/). Bundles the Joplin Terminal CLI as a dependency — no desktop app, no global installs, no external processes to manage.
-Install via npx (no installation required):
+## Quick Start
 ```bash
-npx joplin-mcp-server --help
-```
-## Configuration
-Create a `.env` file with the following variables:
-```
-JOPLIN_HOST=127.0.0.1
-JOPLIN_PORT=41184
-JOPLIN_TOKEN=your_joplin_token
+npx joplin-mcp-server --token your_joplin_token
 ```
-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)**:
-```powershell
-# Forward port 41184 to allow WSL access to Joplin
-netsh interface portproxy add v4tov4 listenport=41184 listenaddress=0.0.0.0 connectport=41184 connectaddress=127.0.0.1
-# Verify the port forward is active
-netsh interface portproxy show all
-```
+That's it. The server spawns its own Joplin Terminal instance (sidecar mode), syncs to your configured backend, and exposes your notes via MCP.
-**Configure your .env file in WSL**:
+## Architecture
-```bash
-# Use your Windows machine's LAN IP address
-JOPLIN_HOST=192.168.0.40  # Replace with your actual Windows IP
-JOPLIN_PORT=41184
-JOPLIN_TOKEN=your_joplin_token
-```
+### Sidecar Mode (Default)
-**To find your Windows IP address**:
+The server bundles `joplin` as an npm dependency and manages its own Joplin Terminal process. No Joplin desktop app needed — the sidecar handles everything: data storage, sync, and the REST API.
 ```bash
-# From WSL
-cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
-# This gives the WSL bridge IP (e.g., 10.255.255.254)
-# Or use your Windows LAN IP (usually 192.168.x.x)
-# Check in Windows: ipconfig (look for IPv4 Address)
-```
-**To remove the port forward later** (if needed):
-```powershell
-netsh interface portproxy delete v4tov4 listenport=41184 listenaddress=0.0.0.0
+# Basic usage — sidecar starts automatically
+npx joplin-mcp-server --token your_token
+# With cloud sync
+npx joplin-mcp-server --token your_token \
+  --sync-target joplin-cloud \
+  --sync-username user@example.com --sync-password pass
+# With filesystem sync (e.g. OneDrive folder)
+npx joplin-mcp-server --token your_token \
+  --sync-target filesystem \
+  --sync-path /mnt/c/Users/you/OneDrive/Joplin
 ```
-**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`
+The Joplin CLI is resolved in this order: `JOPLIN_CLI` env var > `node_modules/.bin/joplin` (bundled) > global install > `npx` fallback.
-2. **Add this configuration to settings.json**:
+Data is stored in `~/.config/joplin-mcp` by default (separate from any desktop Joplin install).
-   ```json
-   {
-     "clipperServer.host": "0.0.0.0"
-   }
-   ```
+### External Mode
-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**:
+Connects to an existing Joplin instance instead of spawning a sidecar. Activated by setting `JOPLIN_HOST` or `JOPLIN_PORT`.
 ```bash
-# Test if Joplin is reachable from WSL
-curl http://192.168.0.40:41184/ping
-# Should return: JoplinClipperServer
-# If using WSL bridge IP:
-curl http://10.255.255.254:41184/ping
+# Connect to Joplin desktop on another machine or Windows host
+JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token
 ```
-**Common issues**:
+## Configuration
+### Environment Variables
-- **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)
+| Variable               | Description                                             | Default                |
+| ---------------------- | ------------------------------------------------------- | ---------------------- |
+| `JOPLIN_TOKEN`         | API token (required)                                    | --                     |
+| `JOPLIN_HOST`          | Connect to existing Joplin at this host (skips sidecar) | --                     |
+| `JOPLIN_PORT`          | Connect to existing Joplin on this port (skips sidecar) | --                     |
+| `JOPLIN_CLI`           | Path to joplin CLI binary (overrides auto-detection)    | --                     |
+| `JOPLIN_PROFILE`       | Joplin data directory for sidecar mode                  | `~/.config/joplin-mcp` |
+| `JOPLIN_SYNC_TARGET`   | Sync target type                                        | `none`                 |
+| `JOPLIN_SYNC_PATH`     | Sync target URL/path                                    | --                     |
+| `JOPLIN_SYNC_USERNAME` | Sync username/email                                     | --                     |
+| `JOPLIN_SYNC_PASSWORD` | Sync password                                           | --                     |
+| `LOG_LEVEL`            | Log level: debug, info, warn, error                     | `info`                 |
-## Command Line Options
+### Command Line Options
 ```
 OPTIONS:
-  --env-file <file>    Load environment variables from file
-  --host <hostname>    Joplin hostname or IP (default: 127.0.0.1)
-  --port <port>        Joplin port (default: 41184)
-  --token <token>      Joplin API token
-  --transport <type>   Transport type: stdio (default) or http
-  --http-port <port>   HTTP server port (default: 3000, only used with --transport http)
-  --help, -h           Show help message
+  --env-file <file>          Load environment variables from file
+  --token <token>            Joplin API token
+  --transport <type>         Transport type: stdio (default) or http
+  --http-port <port>         HTTP server port (default: 3000, only with --transport http)
+  --profile <dir>            Joplin data directory (default: ~/.config/joplin-mcp)
+  --sync-target <type>       Sync target: none, filesystem, webdav, nextcloud,
+                             joplin-cloud, joplin-server, s3, dropbox, onedrive
+  --sync-path <url>          URL or path for sync target
+  --sync-username <user>     Username/email for sync
+  --sync-password <pass>     Password for sync
+  --help, -h                 Show help message
 ```
-### Command Line Usage Examples
+### Path Expansion
-```bash
-# Using command line arguments
-npx joplin-mcp-server --token your_joplin_token
+The `--sync-path` and `--profile` options support `~` and environment variable expansion for cross-platform compatibility:
-# Using environment file
-npx joplin-mcp-server --env-file /path/to/your/.env
+```bash
+# Tilde expands to home directory (Linux, macOS, Windows)
+--sync-path ~/OneDrive/Apps/Joplin
-# WSL: Connect to Windows host
-npx joplin-mcp-server --host 192.168.0.40 --token your_token
+# Environment variables (both forms supported)
+--sync-path ${HOME}/OneDrive/Apps/Joplin
+--sync-path $HOME/OneDrive/Apps/Joplin
-# HTTP mode (for testing with MCP Inspector)
-npx joplin-mcp-server --transport http --token your_token
+# Windows example using USERPROFILE
+--sync-path ${USERPROFILE}/OneDrive/Apps/Joplin
 ```
-### MCP Client Configuration
+This works in MCP client configs (`.mcp.json`, Claude Desktop) where shell expansion isn't available.
+### Sync Targets
-#### Claude Desktop Configuration
+| Target          | Required Options                                                                     |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `none`          | (default, no sync)                                                                   |
+| `filesystem`    | `--sync-path /path/to/dir`                                                           |
+| `webdav`        | `--sync-path <url>` `--sync-username` `--sync-password`                              |
+| `nextcloud`     | `--sync-path <url>` `--sync-username` `--sync-password`                              |
+| `joplin-cloud`  | `--sync-username` `--sync-password`                                                  |
+| `joplin-server` | `--sync-path <url>` `--sync-username` `--sync-password`                              |
+| `s3`            | `--sync-path <bucket>` `--sync-username <access-key>` `--sync-password <secret-key>` |
+| `dropbox`       | (OAuth flow)                                                                         |
+| `onedrive`      | (OAuth flow)                                                                         |
-**Important**: Claude Desktop does NOT support environment variable expansion (`${VAR}` syntax). You must provide values directly.
+## MCP Client Configuration
-**Option 1: Using env Section (Recommended)**
+### Claude Code
-Add to your `claude_desktop_config.json`:
+The repository includes a `.mcp.json` that works with Claude Code's env var expansion:
 ```json
 {
   "mcpServers": {
     "joplin": {
-      "command": "npx",
-      "args": ["joplin-mcp-server"],
+      "command": "node",
+      "args": ["dist/bin.js"],
       "env": {
-        "JOPLIN_TOKEN": "your_actual_token_here",
-        "JOPLIN_PORT": "41184",
-        "JOPLIN_HOST": "127.0.0.1"
+        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
       }
     }
   }
 }
 ```
-**Option 2: Using Command-Line Arguments**
-```json
-{
-  "mcpServers": {
-    "joplin": {
-      "command": "npx",
-      "args": ["joplin-mcp-server", "--token", "your_actual_token_here", "--port", "41184", "--host", "127.0.0.1"]
-    }
-  }
-}
-```
-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`):
+Set `JOPLIN_TOKEN` in your shell (add to `~/.bashrc` or `~/.zshrc`):
 ```bash
 export JOPLIN_TOKEN="your_actual_token_here"
-export JOPLIN_PORT="41184"        # Optional, defaults to 41184
-export JOPLIN_HOST="127.0.0.1"    # Optional, defaults to 127.0.0.1
 ```
-**2. Use the included `.mcp.json` configuration**:
-The repository includes a working `.mcp.json` file that uses environment variable expansion:
-```json
-{
-  "mcpServers": {
-    "joplin": {
-      "command": "npx",
-      "args": ["joplin-mcp-server"],
-      "env": {
-        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
-      }
-    }
-  }
-}
-```
-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).
+### Claude Desktop
-**With environment variables:**
+Claude Desktop does **not** support `${VAR}` expansion. Provide values directly:
 ```json
 {
   "mcpServers": {
     "joplin": {
       "command": "npx",
-      "args": ["joplin-mcp-server"],
-      "env": {
-        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}",
-        "JOPLIN_PORT": "${JOPLIN_PORT}",
-        "JOPLIN_HOST": "${JOPLIN_HOST}"
-      }
+      "args": ["joplin-mcp-server", "--token", "your_actual_token_here"]
     }
   }
 }
 ```
-**With direct values:**
+### With Sync (Claude Desktop)
 ```json
 {
   "mcpServers": {
     "joplin": {
       "command": "npx",
-      "args": ["joplin-mcp-server", "--token", "your_joplin_token", "--port", "41184", "--host", "127.0.0.1"]
+      "args": [
+        "joplin-mcp-server",
+        "--token",
+        "your_token",
+        "--sync-target",
+        "filesystem",
+        "--sync-path",
+        "/path/to/sync/dir"
+      ]
     }
   }
 }
 ```
-**Using environment file:**
+### External Mode
 ```json
 {
   "mcpServers": {
     "joplin": {
       "command": "npx",
-      "args": ["joplin-mcp-server", "--env-file", "/path/to/your/.env"]
+      "args": ["joplin-mcp-server"],
+      "env": {
+        "JOPLIN_TOKEN": "your_actual_token_here",
+        "JOPLIN_HOST": "192.168.0.40",
+        "JOPLIN_PORT": "41184"
+      }
     }
   }
 }
 ```
-## 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:
+### Docker
 ```bash
-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")
+docker build -t joplin-mcp .
+docker run -e JOPLIN_TOKEN=your_token -p 3000:3000 joplin-mcp
 ```
-### search_notes
+## WSL Setup
-Searches for notes in Joplin and returns matching notebooks.
+Running in WSL? The sidecar architecture makes this straightforward — no Windows port forwarding needed.
-**Parameters:**
+### Filesystem Sync via OneDrive (Recommended)
-- `query`: The search query string
+Both your Windows Joplin desktop and the WSL sidecar sync to the same OneDrive folder. They see the same notes without needing to talk to each other directly.
+```bash
+# Point the sidecar at your OneDrive Joplin sync folder
+npx joplin-mcp-server --token your_token \
+  --sync-target filesystem \
+  --sync-path /mnt/c/Users/YourName/OneDrive/Joplin
 ```
-# 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
+In your Joplin desktop app, configure sync to the same OneDrive folder: **Tools > Options > Synchronisation > File system > /Users/YourName/OneDrive/Joplin**
-Reads the full content of a specific note.
+### Cloud Sync
-**Parameters:**
-- `note_id`: The ID of the note to read
+Alternatively, both instances can sync to Joplin Cloud or any other cloud backend:
+```bash
+npx joplin-mcp-server --token your_token \
+  --sync-target joplin-cloud \
+  --sync-username user@example.com --sync-password pass
 ```
-# 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
+### External Mode (Port Forwarding)
-## Agenda
-1. Project status update
-2. Timeline review
-3. Resource allocation
-4. Next steps
+If you prefer to connect directly to Windows Joplin instead of running a sidecar:
-## Notes
-- Project is on track for Q2 delivery
-- Need to allocate additional resources to the UI team
-- Next meeting scheduled for next Friday
+**On Windows (PowerShell as Administrator):**
----
-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"
+```powershell
+netsh interface portproxy add v4tov4 listenport=41184 listenaddress=0.0.0.0 connectport=41184 connectaddress=127.0.0.1
 ```
-> **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
+**In WSL:**
+```bash
+JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token
 ```
-# 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.
----
+Find your Windows IP with `ipconfig` on Windows or `cat /etc/resolv.conf | grep nameserver` from WSL.
-## 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
-```
+## Available Tools
-> **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.
+| Tool             | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `list_notebooks` | Retrieve the complete notebook hierarchy              |
+| `search_notes`   | Search for notes by query string                      |
+| `read_notebook`  | Read contents of a specific notebook                  |
+| `read_note`      | Read full content of a specific note                  |
+| `read_multinote` | Read multiple notes at once                           |
+| `create_note`    | Create a new note                                     |
+| `create_folder`  | Create a new notebook                                 |
+| `edit_note`      | Edit an existing note                                 |
+| `edit_folder`    | Edit an existing notebook                             |
+| `delete_note`    | Delete a note (requires confirmation)                 |
+| `delete_folder`  | Delete a notebook (requires confirmation)             |
+| `sync`           | Trigger a Joplin sync with the configured sync target |
 ## Development
-### Local Development Setup
 ```bash
-# Install dependencies
-pnpm install
-# Build the project
-pnpm build
-# Run tests
-pnpm test
-# Format code
-pnpm format
-# Run linter
-pnpm lint
-# Run validation (format + lint + test + build)
-pnpm validate
-```
-### Testing Local Changes
-```bash
-# Link for local development
-npm link
-# Test the CLI
-npx joplin-mcp-server --help
-# Unlink when done
-npm unlink -g joplin-mcp-server
+pnpm install          # Install dependencies
+pnpm build            # Build to dist/
+pnpm test             # Run tests
+pnpm validate         # Format + lint + typecheck + test + build
+pnpm serve:dev        # Dev mode with hot reload (stdio)
+pnpm serve:dev:http   # Dev mode with hot reload (HTTP)
+pnpm inspect          # Build and open MCP Inspector
 ```
 ## License