joplin-mcp-server 1.2.1 → 2.0.0

package/README.md

@@ -1,520 +1,256 @@
 # Joplin MCP Server
 
-This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin.
+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.
 
 ## Quick Start
 
-Install via npx (no installation required):
-
 ```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.
+That's it. The server spawns its own Joplin Terminal instance (sidecar mode), syncs to your configured backend, and exposes your notes via MCP.
 
-#### Option 1: Windows Port Forwarding (Recommended)
+## Architecture
 
-This is the simplest solution that requires no Joplin configuration changes and persists across reboots.
+### Sidecar Mode (Default)
 
-**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
-```
-
-**Configure your .env file in WSL**:
+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
-# 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
+# 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
 ```
 
-**To find your Windows IP address**:
+The Joplin CLI is resolved in this order: `JOPLIN_CLI` env var > `node_modules/.bin/joplin` (bundled) > global install > `npx` fallback.
 
-```bash
-# From WSL
-cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
-# This gives the WSL bridge IP (e.g., 10.255.255.254)
+Data is stored in `~/.config/joplin-mcp` by default (separate from any desktop Joplin install).
 
-# Or use your Windows LAN IP (usually 192.168.x.x)
-# Check in Windows: ipconfig (look for IPv4 Address)
-```
+### External Mode
 
-**To remove the port forward later** (if needed):
-
-```powershell
-netsh interface portproxy delete v4tov4 listenport=41184 listenaddress=0.0.0.0
-```
-
-**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**:
-
-   ```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**:
+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
-```
-
-### Command Line Usage Examples
-
-```bash
-# Using command line arguments
-npx joplin-mcp-server --token your_joplin_token
-
-# Using environment file
-npx joplin-mcp-server --env-file /path/to/your/.env
-
-# WSL: Connect to Windows host
-npx joplin-mcp-server --host 192.168.0.40 --token your_token
-
-# HTTP mode (for testing with MCP Inspector)
-npx joplin-mcp-server --transport http --token your_token
+  --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
 ```
 
-### MCP Client Configuration
+### 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**:
+### Claude Desktop
 
-The repository includes a working `.mcp.json` file that uses environment variable expansion:
+Claude Desktop does **not** support `${VAR}` expansion. Provide values directly:
 
 ```json
 {
   "mcpServers": {
     "joplin": {
       "command": "npx",
-      "args": ["joplin-mcp-server"],
-      "env": {
-        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
-      }
+      "args": ["joplin-mcp-server", "--token", "your_actual_token_here"]
     }
   }
 }
 ```
 
-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 Sync (Claude Desktop)
 
 ```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_token",
+        "--sync-target",
+        "filesystem",
+        "--sync-path",
+        "/path/to/sync/dir"
+      ]
     }
   }
 }
 ```
 
-**With direct values:**
+### External Mode
 
 ```json
 {
   "mcpServers": {
     "joplin": {
       "command": "npx",
-      "args": ["joplin-mcp-server", "--token", "your_joplin_token", "--port", "41184", "--host", "127.0.0.1"]
-    }
-  }
-}
-```
-
-**Using environment file:**
-
-```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

package/dist/bin.d.ts

@@ -1 +1 @@
-#!/usr/bin/env node
+export { };