### Execute CLI Commands

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/INDEX.md

Start the server or run the setup wizard using the command line interface.

```bash
joplin-mcp-server                    # Start server (auto-discover config)
joplin-mcp-server --config ./config.json   # With explicit config
joplin-mcp-server --transport http --port 8000  # HTTP transport
joplin-mcp-install                   # Interactive setup wizard
```

--------------------------------

### Install from PyPI

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Standard installation command for the package.

```bash
pip install joplin-mcp
```

--------------------------------

### Get Note Examples

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/note-management.md

Usage examples for retrieving full notes and specific line ranges.

```python
# Get note with default formatting
result = await get_note("6f66edaf4e72452da2019e8733b2a39d")
print(result)

# Read lines 51-100
result = await get_note("6f66edaf4e72452da2019e8733b2a39d", start_line=51)
print(result)
```

--------------------------------

### Get Note Resources Examples

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/note-management.md

Usage examples for retrieving all resources or filtering for OCR text only.

```python
# Get all resources with OCR text
result = await get_note_resources("6f66edaf4e72452da2019e8733b2a39d")
print(result)

# Get only OCR text (useful for document analysis)
result = await get_note_resources("6f66edaf4e72452da2019e8733b2a39d", ocr_only=True)
print(result)
```

--------------------------------

### Automated setup for Jan AI

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Alternative automated installation script for Jan AI integration.

```bash
# Install and configure Jan AI automatically (if Jan is already installed)
pip install joplin-mcp
joplin-mcp-install
```

--------------------------------

### Get Links Example

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/note-management.md

Example of extracting links from a note and the expected output format.

```python
result = await get_links("6f66edaf4e72452da2019e8733b2a39d")
# Output:
# LINKS_IN_NOTE: ...
# TOTAL_LINKS: 3
# LINK_1:
#   text: Project Alpha
#   target_id: abc...
#   target_title: Project Alpha
#   target_notebook: Work/Projects
```

--------------------------------

### Perform User-Level Installation

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Install the package for the current user to avoid permission issues in system directories.

```bash
pip install --user -e .
```

--------------------------------

### Prepare Test Environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Commands to install dependencies and verify test configuration.

```bash
# Ensure test dependencies are installed
pip install -e ".[dev]"

# Check test configuration
pytest --collect-only
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/core-server.md

Common command-line invocations for starting the Joplin MCP server with various configurations.

```bash
# Run with auto-discovered config
joplin-mcp-server

# STDIO transport (default, most compatible)
joplin-mcp-server --config ~/.joplin-mcp.json

# HTTP transport on custom port
joplin-mcp-server --transport http --port 8080

# Debug logging to file
joplin-mcp-server --log-level debug --log-file server.log
```

--------------------------------

### Initialize ImportOptions Instance

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/import-engine.md

Example of instantiating ImportOptions with custom configuration values.

```python
from joplin_mcp.imports.types import ImportOptions

options = ImportOptions(
    target_notebook="Archive/Imported",
    create_missing_notebooks=True,
    preserve_timestamps=True,
    handle_duplicates="rename",
    max_batch_size=50,
)
```

--------------------------------

### Install in Development Mode

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Use this command to install the package in editable mode from the project root.

```bash
cd joplin-mcp
pip install -e .
```

--------------------------------

### Install and configure Claude Desktop

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Automated installation script for Claude Desktop using pip or uvx.

```bash
# Install and configure everything automatically (pip)
pip install joplin-mcp
joplin-mcp-install

# Or use zero-install with uvx (recommended if you have uv)
uvx --from joplin-mcp joplin-mcp-install

# Optional: pin a specific version/range for stability
uvx --from joplin-mcp==0.4.1 joplin-mcp-install
uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install
```

--------------------------------

### Run Server with CLI Options

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Start the server using command-line arguments for configuration, transport, and logging.

```bash
joplin-mcp-server --config /path/to/joplin-mcp.json \
  --transport stdio \
  --log-level info \
  --log-file /var/log/joplin-mcp.log
```

--------------------------------

### Run via Docker

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Example command to launch the server using Docker with environment variables for configuration.

```bash
docker run -e JOPLIN_TOKEN=your_token \
  -e JOPLIN_HOST=joplin \
  -e JOPLIN_PORT=41184 \
  -e MCP_TRANSPORT=http \
  -p 8000:8000 \
  joplin-mcp
```

--------------------------------

### Start Joplin MCP Server

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Commands to launch the server via pip installation or from the development repository.

```bash
# For pip install
joplin-mcp-server --config ~/.joplin-mcp.json

# For development (from repo)
PYTHONPATH=src python -m joplin_mcp.server --config ./joplin-mcp.json
```

--------------------------------

### Create Notebook Usage

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Examples for creating root, nested, and emoji-labeled notebooks.

```python
# Create root notebook
result = await create_notebook("Work")

# Create nested notebook
result = await create_notebook("Projects", parent_name="Work")

# Create with emoji
result = await create_notebook("Urgent", parent_name="Work", emoji="🔴")

# Create deep nesting (auto-creates parents)
result = await create_notebook("Q1 Tasks", parent_name="Work/Projects/2024")
```

--------------------------------

### Advanced Batch Import Example

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/import-engine.md

Demonstrates initializing the engine and executing a batch import with specific configuration options.

```python
from joplin_mcp.imports.engine import JoplinImportEngine
from joplin_mcp.imports.types import ImportedNote, ImportOptions
from joplin_mcp.fastmcp_server import get_joplin_client
from joplin_mcp.config import get_config

# Create notes to import
notes = [
    ImportedNote(
        title="Note 1",
        body="Content 1",
        notebook="Work",
        tags=["important"]
    ),
    ImportedNote(
        title="Note 2",
        body="Content 2",
        notebook="Work/Projects",
        tags=["urgent"]
    ),
]

# Set up engine
client = get_joplin_client()
config = get_config()
engine = JoplinImportEngine(client, config)

# Configure import
options = ImportOptions(
    target_notebook="Imported",
    create_missing_notebooks=True,
    create_missing_tags=True,
    handle_duplicates="skip",
    preserve_timestamps=True
)

# Import
result = await engine.import_batch(notes, options)
print(f"Imported {result.successful_imports} notes")
for error in result.errors:
    print(f"Error: {error}")
```

--------------------------------

### Install dependencies

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Use this command to resolve 'Module not found' errors.

```bash
pip install -e .
```

--------------------------------

### Check File Permissions

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Verify directory access and ensure the setup script is executable.

```bash
ls -la /path/to/joplin-mcp
chmod +x setup.py
```

--------------------------------

### Catch ConfigError

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/errors.md

Example of handling configuration errors during initialization.

```python
from joplin_mcp.config import ConfigError, get_config

try:
    config = get_config()
except ConfigError as e:
    print(f"Configuration error: {e}")
    # Fix config and retry
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Isolate dependencies by creating a virtual environment before installation.

```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows
pip install -e .
```

--------------------------------

### Verify system requirements and installation

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Checks the Python version, Joplin service status, and package installation via the command line.

```bash
# Check Python version
python --version  # Should be 3.8+

# Check if Joplin is running
curl -s http://localhost:41184/ping || echo "Joplin not responding"

# Check if required packages are installed
python -c "import joplin_mcp; print('✅ joplin_mcp installed')" 2>/dev/null || echo "❌ joplin_mcp not installed"
```

--------------------------------

### Install Joplin MCP via Development Script

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Clone the repository and run the bootstrap script to set up the environment.

```bash
git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
python bootstrap.py
```

--------------------------------

### Execute file and directory imports

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/import-engine.md

Examples of importing single files, entire directories, and handling duplicates.

```python
# Import single Markdown file
result = await import_from_file(
    "/home/user/notes/project.md",
    notebook_name="Work/Projects"
)
print(result)

# Import entire directory, preserving structure
result = await import_from_file(
    "/home/user/documents/",
    notebook_name="Imported"
)
print(result)

# Import with duplicate overwrite
result = await import_from_file(
    "/home/user/backup.jex",
    handle_duplicates="overwrite"
)
print(result)
```

--------------------------------

### Instantiate ImportedNote

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/import-engine.md

Example of creating an ImportedNote instance with specific metadata and content.

```python
from joplin_mcp.imports.types import ImportedNote
from datetime import datetime

note = ImportedNote(
    title="Imported Note",
    body="# Content\n\nThis is the note content.",
    notebook="Archive/2024",
    tags=["imported", "review"],
    is_todo=False,
    created_time=datetime.now()
)
```

--------------------------------

### Run the container with SSE transport

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Starts the container configured for SSE streaming transport.

```bash
docker run --rm \
  -p 8000:8000 \
  -e JOPLIN_TOKEN=your_api_token \
  -e MCP_TRANSPORT=sse \
  joplin-mcp
```

--------------------------------

### Joplin MCP Server Execution Examples

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Various command-line configurations for different transport protocols and logging settings.

```bash
# STDIO transport (default) with auto-discovered config
joplin-mcp-server

# Explicit config file
joplin-mcp-server --config ~/.joplin-mcp.json

# HTTP transport on port 8000
joplin-mcp-server --transport http --port 8000

# SSE transport with logging
joplin-mcp-server --transport sse --log-level debug --log-file server.log

# HTTP-compat mode (modern + legacy endpoints)
joplin-mcp-server --transport http-compat --port 8000
```

--------------------------------

### Update notebook properties

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Examples demonstrating how to rename, change icons, or move notebooks using the update_notebook tool.

```python
# Rename
result = await update_notebook(notebook_id, title="New Name")

# Set emoji
result = await update_notebook(notebook_id, emoji="📚")

# Clear emoji
result = await update_notebook(notebook_id, emoji="")

# Move under different parent
result = await update_notebook(notebook_id, parent_name="Work")

# Move to root
result = await update_notebook(notebook_id, parent_name="/")

# Rename and move in one call
result = await update_notebook(
    notebook_id,
    title="Archived",
    parent_name="Archive"
)
```

--------------------------------

### Verify Python Environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Commands to verify Python installation and package availability.

```bash
# Ensure Python is in PATH
which python
python -c "import joplin_mcp; print('OK')"
```

--------------------------------

### Apply Type Annotations

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Example of using proper type annotations in Python.

```python
# Use proper type annotations
from typing import Optional, List, Dict, Any

def my_function(param: Optional[str] = None) -> Dict[str, Any]:
    return {"result": param or "default"}
```

--------------------------------

### Verify FastMCP Import

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Test the installation by attempting to import FastMCP from the command line.

```bash
python -c "from fastmcp import FastMCP; print('OK')"
```

--------------------------------

### Configure Project Scripts

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

Define the entry points for the Joplin MCP server and installation utilities in the project configuration.

```toml
[project.scripts]
joplin-mcp = "joplin_mcp.server:main"
joplin-mcp-server = "joplin_mcp.server:main"
joplin-mcp-install = "joplin_mcp.install:main"
```

--------------------------------

### Configure HTTP client for MCP

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Example configuration for MCP clients that support network transports.

```json
{
  "mcpServers": {
    "joplin": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

--------------------------------

### joplin-mcp-server CLI

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

The main entry point for starting the Joplin MCP server via command line.

```APIDOC
## CLI Command: joplin-mcp-server

### Description
Starts the Joplin MCP server. Supports various transport protocols and configuration options.

### Arguments
- **--version**: Show version
- **--config**: Path to config file
- **--transport**: stdio (default), http, http-compat, streamable-http, sse
- **--host**: Host for HTTP transports
- **--port**: Port for HTTP transports
- **--path**: HTTP path
- **--log-level**: debug, info, warning, error
- **--log-file**: Write logs to file
```

--------------------------------

### Mock Joplin Client for Testing

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Example of using unittest.mock to simulate the Joplin client.

```python
# Use mock client for testing
from unittest.mock import Mock

mock_client = Mock()
mock_client.ping.return_value = True
server = JoplinMCPServer(client=mock_client)
```

--------------------------------

### Configure Claude Desktop for Joplin MCP

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Add the Joplin MCP server to the Claude Desktop configuration file using either uvx or an installed package.

```json
{
  "mcpServers": {
    "joplin": {
      "command": "uvx",
      "args": ["--from", "joplin-mcp", "joplin-mcp-server"],
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp-server",
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}
```

--------------------------------

### Create Isolated Test Environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Sets up a clean Python virtual environment and installs the package in editable mode to verify core functionality.

```bash
# Create clean environment
python -m venv test_env
source test_env/bin/activate

# Install only required packages
pip install -e .

# Test basic functionality
python -c "from joplin_mcp import JoplinMCPServer; print('OK')"
```

--------------------------------

### Delete a notebook usage example

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Demonstrates how to call delete_notebook with a specific notebook ID.

```python
result = await delete_notebook("abc123def456...")
# Recoverable via restore_from_trash(item_id, item_type='notebook')
```

--------------------------------

### Run Joplin MCP Server via CLI

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Basic command to start the server using the default stdio transport.

```bash
joplin-mcp-server [OPTIONS]
```

--------------------------------

### Run the container with HTTP transport

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Starts the container using the default HTTP transport with the required Joplin API token.

```bash
docker run --rm \
  -p 8000:8000 \
  -e JOPLIN_TOKEN=your_api_token \
  joplin-mcp
```

--------------------------------

### Verify Virtual Environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Check the active Python interpreter and installed packages to ensure the environment is correctly configured.

```bash
# Verify you're in the correct environment
which python
pip list | grep joplin
```

--------------------------------

### Run Joplin MCP Server with different transports

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Commands to start the server using either STDIO or HTTP transport modes.

```bash
# STDIO (default)
joplin-mcp-server --config ~/.joplin-mcp.json

# HTTP transport (development, from repo)
PYTHONPATH=src python -m joplin_mcp.server --transport http --port 8000 --config ./joplin-mcp.json

# Opt-in HTTP compatibility bundle (modern + legacy SSE endpoints)
PYTHONPATH=src python -m joplin_mcp.server --transport http-compat --port 8000 --config ./joplin-mcp.json
# or keep --transport http and export MCP_HTTP_COMPAT=1/true to toggle the same behavior.
```

--------------------------------

### Initialize Default Configuration

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Instantiate the server with minimal parameters to use default host, port, and timeout settings.

```python
# Use minimal configuration
server = JoplinMCPServer(token="your_token")
# Uses defaults: localhost:41184, 30s timeout
```

--------------------------------

### Load Configuration from File

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Initialize the server using a configuration object loaded from a specific file path.

```python
from joplin_mcp import JoplinMCPConfig

config = JoplinMCPConfig.from_file("/path/to/config.json")
server = JoplinMCPServer(config=config)
```

--------------------------------

### Install Claude Code plugin

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Commands to add and install the Joplin MCP plugin within the Claude Code environment.

```bash
/plugin marketplace add alondmnt/joplin-mcp
/plugin install joplin-mcp
```

--------------------------------

### Catch ImportProcessingError

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/errors.md

Example of handling critical errors during the import process.

```python
from joplin_mcp.imports.types import ImportProcessingError

try:
    result = await import_from_file(file_path, notebook_name="Target")
except ImportProcessingError as e:
    print(f"Import failed: {e}")
    # Check result for partial success details
```

--------------------------------

### Catch ImportValidationError

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/errors.md

Example of handling validation errors during file imports.

```python
from joplin_mcp.imports.types import ImportValidationError

try:
    result = await import_from_file(file_path)
except ImportValidationError as e:
    print(f"Validation error: {e}")
```

--------------------------------

### Create Configuration File

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Generate a JSON configuration file in the project directory to store connection settings.

```bash
# Create in project directory
cat > joplin_config.json << EOF
{
  "joplin": {
    "token": "your_token_here",
    "host": "localhost",
    "port": 41184,
    "timeout": 30
  }
}
EOF
```

--------------------------------

### Initialize Notebook Resolver

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/core-server.md

Binds a Joplin client factory to the notebook resolver at server startup.

```python
from joplin_mcp.notebook_utils import init_resolver
from joplin_mcp.fastmcp_server import get_joplin_client

init_resolver(lambda: get_joplin_client())
```

--------------------------------

### Catch AllowlistDeniedError

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/errors.md

Example of handling access denial when performing note operations.

```python
from joplin_mcp.notebook_utils import AllowlistDeniedError

try:
    note = await get_note(note_id)
except AllowlistDeniedError:
    print("Access denied: note is in a restricted notebook")
```

--------------------------------

### main(config_file, transport, host, port, path, log_level)

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/core-server.md

Programmatic initialization and orchestration for the FastMCP server.

```APIDOC
## main(config_file, transport, host, port, path, log_level)

### Description
FastMCP server initialization and orchestration function.

### Parameters
- **config_file** (Optional[str]) - Optional - Path to config file; auto-discovers if None
- **transport** (str) - Optional - Transport protocol
- **host** (str) - Optional - Host for HTTP-based transports
- **port** (int) - Optional - Port for HTTP-based transports
- **path** (str) - Optional - HTTP path for MCP endpoint
- **log_level** (str) - Optional - Log verbosity

### Returns
- **int** - 0 on success, 1 on error
```

--------------------------------

### Configure via JSON File

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Define the token and server connection details in a configuration file.

```json
{
  "joplin": {
    "token": "your_token_here",
    "host": "localhost",
    "port": 41184
  }
}
```

--------------------------------

### Set Connection Environment Variables

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Configure API token, host, port, timeout, and SSL verification settings.

```bash
export JOPLIN_TOKEN="your_api_token"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"
export JOPLIN_VERIFY_SSL="false"
```

--------------------------------

### Error sanitization example

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/errors.md

Demonstrates how sensitive information like paths and tokens are redacted from error messages.

```text
Before sanitization:
Failed at /home/user/app.py:42 with token=abc123&port=8000
at someFunction (/usr/local/lib/node_modules/joplin/index.js:100)

After sanitization:
Failed at <path> with token=***&port=8000
```

--------------------------------

### Run the container with mounted configuration

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Mounts a local configuration file into the container as read-only.

```bash
docker run --rm \
  -p 8000:8000 \
  -v $PWD/joplin-mcp.json:/config/joplin-mcp.json:ro \
  joplin-mcp
```

--------------------------------

### Execute note searches

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/note-management.md

Demonstrates searching, listing todos, and paginating through results.

```python
# Search for Python-related notes
result = await find_notes("python", limit=20)
print(result)

# List all todos, completed first
result = await find_notes("*", task=True, order_by="iscompleted", order_dir="desc")
print(result)

# Paginate through results (25 per page)
result = await find_notes("search term", limit=25, offset=0)
# ... display page 1 ...
result = await find_notes("search term", limit=25, offset=25)
# ... display page 2 ...
```

--------------------------------

### Fix corrupted fastmcp installation

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Run this command to resolve import errors related to corrupted fastmcp packages.

```bash
pip install --force-reinstall --no-deps fastmcp==X fastmcp-slim==X
```

--------------------------------

### main() (CLI Entry Point)

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/core-server.md

The primary CLI entry point for the Joplin MCP server. It parses command-line arguments and launches the FastMCP server.

```APIDOC
## main() (CLI Entry Point)

### Description
CLI entry point for the server. Parses command-line arguments and launches the FastMCP server.

### Parameters
- **--version** (flag) - Optional - Show version and exit
- **--config** (path) - Optional - Path to config file (JSON/YAML)
- **--transport** (enum) - Optional - Transport protocol (stdio, http, http-compat, streamable-http, sse)
- **--host** (string) - Optional - Host for HTTP transports
- **--port** (int) - Optional - Port for HTTP transports
- **--path** (string) - Optional - HTTP path for MCP endpoint
- **--log-level** (enum) - Optional - Log verbosity (debug, info, warning, error)
- **--log-file** (path) - Optional - Write logs to file

### Returns
- **int** - 0 on success, 1 on error
```

--------------------------------

### Force Reinstall FastMCP Dependencies

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Fix corrupted fastmcp installations by forcing a reinstall of both the shim and the core package.

```bash
pip install --force-reinstall --no-deps fastmcp==3.4.2 fastmcp-slim==3.4.2
```

--------------------------------

### Import Python Entry Points

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/INDEX.md

Access server components and configuration utilities within Python scripts.

```python
from joplin_mcp.server import main          # CLI
from joplin_mcp.fastmcp_server import main  # FastMCP server
from joplin_mcp.config import get_config    # Get config
from joplin_mcp import JoplinMCPConfig      # Config class
```

--------------------------------

### Collect System and Configuration Info

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Commands to gather environment details and configuration settings for troubleshooting reports, ensuring sensitive tokens are masked.

```bash
# System information
python --version
pip list | grep -E "(joplin|mcp)"
uname -a  # Linux/macOS
systeminfo  # Windows

# Configuration (remove sensitive tokens)
echo "Host: $JOPLIN_HOST"
echo "Port: $JOPLIN_PORT"
echo "Token: ${JOPLIN_TOKEN:0:8}..."

# Error messages
# Include full error traceback
```

--------------------------------

### Configure OllMCP

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Commands for setting up OllMCP with auto-discovery or manual server configuration.

```bash
# Install ollmcp
pip install ollmcp

# Run with auto-discovery (requires existing Claude Desktop config)
ollmcp --auto-discovery --model qwen3:4b
```

```bash
# Install ollmcp
pip install ollmcp

# Set environment variable
export JOPLIN_TOKEN="your_joplin_api_token_here"

# Run with uvx (requires uv installed)
ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b

# Or with an installed package (pip install joplin-mcp)
ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b
```

--------------------------------

### Set Content Exposure Environment Variables

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Configure content visibility levels and preview length via environment variables.

```bash
export JOPLIN_CONTENT_EXPOSURE_SEARCH_RESULTS="preview"
export JOPLIN_CONTENT_EXPOSURE_INDIVIDUAL_NOTES="full"
export JOPLIN_CONTENT_EXPOSURE_LISTINGS="none"
export JOPLIN_CONTENT_EXPOSURE_MAX_PREVIEW_LENGTH="300"
```

--------------------------------

### Partial Operation Status Report

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/notebook-allowlist.md

Example output for bulk operations where some notes are blocked and others are processed successfully.

```text
OPERATION: TAG_NOTE
STATUS: PARTIAL
TOTAL_OPS: 4
SUCCEEDED: 2
FAILED: 2
FAILURES:
  - note_id=abc... error="Notebook not accessible"
  - note_id=def... error="Notebook not accessible"
```

--------------------------------

### Create single-level notebook structure

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Initializes a parent notebook and child notebooks using the parent_name parameter.

```python
await create_notebook("Work")
await create_notebook("Project A", parent_name="Work")
await create_notebook("Project B", parent_name="Work")
```

--------------------------------

### Initialize and Manage Notebook Resolver

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

Functions for notebook caching, path resolution, and allowlist enforcement.

```python
def init_resolver(client_factory: Callable[[], ClientApi]) -> None
    """Initialize notebook resolver with client factory."""

def get_notebook_id_by_name(
    notebook_name: str,
    allowlist_entries: Optional[List[str]] = None,
) -> str
    """Resolve notebook name/path to ID."""

def is_notebook_accessible(
    notebook_id: str,
    allowlist_entries: Optional[List[str]] = None,
) -> bool
    """Check if notebook is accessible under allowlist."""

def validate_notebook_access(
    notebook_id: str,
    allowlist_entries: Optional[List[str]] = None,
) -> None
    """Validate access or raise AllowlistDeniedError."""

def get_notebook_map_cached() -> Dict[str, Dict[str, Optional[str]]]
    """Get cached notebook map."""

def invalidate_notebook_cache() -> None
    """Clear notebook cache (forces refresh on next use)."""

def _compute_notebook_path(
    notebook_id: str,
    notebook_map: Dict[str, Dict[str, Optional[str]]]
) -> str
    """Compute full hierarchical path for notebook."""

def _build_notebook_map(items: List[Any]) -> Dict[str, Dict[str, Optional[str]]]
    """Build notebook map from items list."""
```

--------------------------------

### Project File Structure

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MANIFEST.md

Displays the directory layout of the generated documentation files.

```text
output/
├── COMPLETION_SUMMARY.txt
├── MANIFEST.md (this file)
├── INDEX.md
├── README.md
├── MODULES.md
├── configuration.md
├── types.md
├── errors.md
├── notebook-allowlist.md
└── api-reference/
    ├── core-server.md
    ├── note-management.md
    ├── notebook-management.md
    ├── tag-management.md
    ├── trash-management.md
    └── import-engine.md
```

--------------------------------

### Configure Global Access with Exclusions

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/notebook-allowlist.md

Demonstrates the difference between single-level and recursive wildcard exclusions.

```json
{
  "notebook_allowlist": [
    "*",
    "!Personal",
    "!Finance",
    "!Medical",
    "!Legal"
  ]
}
```

```json
{
  "notebook_allowlist": [
    "**",
    "!Personal",
    "!Finance",
    "!Medical"
  ]
}
```

--------------------------------

### Scenario C: Joplin MCP Config - Empty Allowlist (Deny-All)

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/agent-smoke-tests.md

Configuration for the Joplin MCP agent with an empty notebook allowlist, effectively denying access to all notebooks.

```json
{ "token": "...", "host": "127.0.0.1", "port": 41184,
  "notebook_allowlist": [] }
```

--------------------------------

### Create a note with a parent notebook

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/errors.md

List existing notebooks and ensure the parent structure exists before creating a new note.

```python
# Check available notebooks
notebooks = await list_notebooks()

# Create parent if needed
await create_notebook("Work")
await create_notebook("Projects", parent_name="Work")

# Then create note
await create_note("Title", notebook_name="Work/Projects")
```

--------------------------------

### Manage Server Lifecycle

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Use an asynchronous context manager to ensure the server resources are cleaned up automatically.

```python
async with JoplinMCPServer(token="your_token") as server:
    # Server automatically cleaned up
    results = await server.handle_find_notes({"query": "test"})
```

--------------------------------

### Configure Notebook Allowlist in Configuration Files

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/notebook-allowlist.md

Define the allowlist using JSON or YAML formats in the project configuration file.

```json
{
  "notebook_allowlist": ["Work", "Projects/*", "!Projects/Secret"]
}
```

```yaml
notebook_allowlist:
  - Work
  - Projects/*
  - "!Projects/Secret"
```

--------------------------------

### Configure Connection Settings

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/INDEX.md

Define the server connection parameters including API token, host, port, and SSL verification.

```json
{
  "token": "required_api_token",
  "host": "localhost",
  "port": 41184,
  "timeout": 30,
  "verify_ssl": false
}
```

--------------------------------

### Create Notebook Definition

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Signature for the create_notebook tool.

```python
async def create_notebook(
    title: RequiredStringType,
    parent_name: Optional[RequiredStringType] = None,
    emoji: Optional[str] = None,
) -> str
```

--------------------------------

### Import JEX Backup

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/import-engine.md

Restore notes from a Joplin export file.

```python
# Restore from Joplin export
result = await import_from_file(
    "/backups/joplin-export-2024-01-15.jex",
    notebook_name="Restored Backup"
)
```

--------------------------------

### Build the Docker image

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Builds the joplin-mcp container image from the current directory.

```bash
docker build -t joplin-mcp .
```

--------------------------------

### Configure Content Exposure via JSON

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Define content visibility levels and preview lengths in the configuration file.

```json
{
  "content_exposure": {
    "search_results": "preview",
    "individual_notes": "full",
    "listings": "none",
    "max_preview_length": 300
  }
}
```

--------------------------------

### Create Sub-Notebook and Notes

Source: https://github.com/alondmnt/joplin-mcp/blob/main/skills/joplin/SKILL.md

Create nested notebooks and add notes to them. Specify the parent notebook by name or path for sub-notebooks.

```python
create_notebook("Sub")              # top-level notebook: omit parent_name
create_notebook("Sub", parent_name="Projects/Work")  # under an existing notebook (by name or path)
create_note("Title", notebook_name="Sub", body="...")
```

--------------------------------

### Configuration Management Functions and Exceptions

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

Utilities for retrieving, updating, and validating server configuration.

```python
def get_config() -> JoplinMCPConfig
    """Get current server configuration."""

def set_config(config: JoplinMCPConfig) -> None
    """Update server configuration."""

class ConfigError(Exception)
    """Configuration validation errors."""

class ConfigParser
    """Helper for parsing config values."""

class ConfigValidator
    """Helper for validating config values."""
```

--------------------------------

### Verify Server Capabilities

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Python script to list available tools from the Joplin MCP server.

```python
server = JoplinMCPServer(token="your_token")
tools = server.get_available_tools()
print(f"Available tools: {len(tools)}")
for tool in tools:
    print(f"- {tool.name}: {tool.description}")
```

--------------------------------

### Set Environment Variables for Connection

Source: https://github.com/alondmnt/joplin-mcp/blob/main/README.md

Configure connection settings using shell environment variables as an alternative to JSON files.

```bash
# Connection settings
export JOPLIN_TOKEN="your_api_token_here"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"
```

--------------------------------

### Configure development environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

A permissive configuration enabling destructive operations and disabling SSL verification for local testing.

```json
{
  "token": "your_token",
  "host": "localhost",
  "port": 41184,
  "timeout": 30,
  "verify_ssl": false,
  "tools": {
    "delete_note": true,
    "delete_notebook": true,
    "delete_tag": true,
    "import_from_file": true,
    "update_notebook": true,
    "update_tag": true
  }
}
```

--------------------------------

### List Notebooks Usage

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Retrieve and display the formatted notebook tree.

```python
result = await list_notebooks()
print(result)
```

--------------------------------

### Configure Notebook Allowlist via Environment Variable

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/notebook-allowlist.md

Set the allowlist using a comma-separated string in the JOPLIN_NOTEBOOK_ALLOWLIST environment variable.

```bash
export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/*,!Projects/Secret"
```

--------------------------------

### Create Note with create_note()

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/note-management.md

Use this function to generate new notes, optionally specifying a notebook path, todo status, and due date.

```python
async def create_note(
    title: RequiredStringType,
    notebook_name: Optional[RequiredStringType] = None,
    body: Optional[str] = None,
    is_todo: Optional[bool] = None,
    todo_due: Optional[int] = None,
) -> str
```

```python
# Simple note
result = await create_note("My First Note", body="This is a note")

# Note in nested notebook
result = await create_note(
    "Project Plan",
    notebook_name="Work/Projects",
    body="## Overview\n...",
)

# Todo with due date
import time
due_ms = int((time.time() + 86400) * 1000)  # Tomorrow
result = await create_note(
    "Buy groceries",
    is_todo=True,
    todo_due=due_ms,
)
```

--------------------------------

### Initialize JoplinImportEngine

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

Defines the main engine class for batch note processing.

```python
class JoplinImportEngine:
    def __init__(self, client: ClientApi, config: JoplinMCPConfig)
    
    async def import_batch(
        self,
        notes: List[ImportedNote],
        options: ImportOptions
    ) -> ImportResult
        """Process batch of notes for import."""
```

--------------------------------

### Scenario A: Joplin MCP Config - No Allowlist

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/agent-smoke-tests.md

Configuration for the Joplin MCP agent when no notebook allowlist is specified. This allows access to all notebooks.

```json
{ "token": "...", "host": "127.0.0.1", "port": 41184 }
```

--------------------------------

### Configure minimal environment variables

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

Sets the required Joplin token using environment variables while relying on default connection settings.

```bash
export JOPLIN_TOKEN="your_token"
# Uses all defaults: localhost:41184, 30s timeout, all tools enabled
```

--------------------------------

### Pass Token Directly in Python

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/troubleshooting.md

Initialize the JoplinMCPServer instance by passing the token as an argument.

```python
server = JoplinMCPServer(token="your_token_here")
```

--------------------------------

### FastMCP Server Initialization

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/core-server.md

The function signature for initializing the FastMCP server programmatically.

```python
def main(
    config_file: Optional[str] = None,
    transport: str = "stdio",
    host: str = "127.0.0.1",
    port: int = 8000,
    path: str = "/mcp",
    log_level: str = "info",
) -> int
```

--------------------------------

### Notebook Management Tools

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

Methods for listing, creating, updating, and deleting notebooks.

```APIDOC
## list_notebooks

### Description
Retrieves a list of all available notebooks.

## create_notebook

### Description
Creates a new notebook.

### Parameters
- **title** (RequiredStringType) - Required - Notebook title
- **parent_name** (RequiredStringType) - Optional - Parent notebook name
- **emoji** (str) - Optional - Notebook emoji icon
```

--------------------------------

### Configure production environment

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/configuration.md

A restrictive configuration enforcing SSL, limiting tool access, and defining content exposure rules.

```json
{
  "token": "your_token",
  "host": "joplin.internal.company.com",
  "port": 443,
  "timeout": 60,
  "verify_ssl": true,
  "notebook_allowlist": ["Work", "!Work/Private"],
  "tools": {
    "create_note": true,
    "update_note": true,
    "find_notes": true,
    "delete_note": false,
    "delete_notebook": false,
    "delete_tag": false,
    "import_from_file": false
  },
  "content_exposure": {
    "search_results": "preview",
    "individual_notes": "full",
    "listings": "none",
    "max_preview_length": 500
  }
}
```

--------------------------------

### create_notebook()

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/notebook-management.md

Creates a new notebook at the root level or under a specified parent path.

```APIDOC
## create_notebook()

### Description
Create a new notebook at root level or under a parent. Supports auto-creation of parent hierarchy if allowed.

### Signature
`async def create_notebook(title: RequiredStringType, parent_name: Optional[RequiredStringType] = None, emoji: Optional[str] = None) -> str`

### Parameters
- **title** (RequiredStringType) - Required - Notebook name (non-empty, unique at parent level)
- **parent_name** (str) - Optional - Parent notebook name/path (e.g., "Work" or "Work/Projects"); None = root
- **emoji** (str) - Optional - Single emoji icon (e.g., "📝", "💼"); empty string = no icon

### Returns
- **str** - Success message with new notebook ID and path

### Raises
- **ValueError** - Title empty, parent not found, or duplicate name
- **AllowlistDeniedError** - Parent notebook in blocked list

### Example
```python
# Create root notebook
result = await create_notebook("Work")

# Create nested notebook
result = await create_notebook("Projects", parent_name="Work")

# Create with emoji
result = await create_notebook("Urgent", parent_name="Work", emoji="🔴")
```
```

--------------------------------

### Full Access Configuration

Source: https://github.com/alondmnt/joplin-mcp/blob/main/docs/content-privacy.md

Maximizes functionality by exposing content broadly. Search results and individual notes are fully accessible, listings show previews, and smart TOC is enabled.

```json
{
  "content_exposure": {
    "search_results": "full",
    "individual_notes": "full",
    "listings": "preview",
    "max_preview_length": 500,
    "smart_toc_threshold": 2000,
    "enable_smart_toc": true
  }
}
```

--------------------------------

### get_config()

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/core-server.md

Retrieves the current server configuration object.

```APIDOC
## get_config()

### Description
Retrieves the current server configuration object.

### Signature
`def get_config() -> JoplinMCPConfig`

### Parameters
None

### Returns
`JoplinMCPConfig` instance
```

--------------------------------

### Define Server CLI Entry Point

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/MODULES.md

Signature for the main CLI entry point used by the joplin-mcp-server command.

```python
def main() -> int
    """
    CLI entry point.
    
    Args (via argparse):
        --version: Show version
        --config: Path to config file
        --transport: stdio (default), http, http-compat, streamable-http, sse
        --host: Host for HTTP transports
        --port: Port for HTTP transports
        --path: HTTP path
        --log-level: debug, info, warning, error
        --log-file: Write logs to file
    
    Returns:
        0 on success, 1 on error
    """
```

--------------------------------

### Configure Multiple Project Trees

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/notebook-allowlist.md

Allows access to specific project trees while denying access to others not listed.

```json
{
  "notebook_allowlist": ["Projects/Alpha", "Projects/Beta", "Projects/Gamma"]
}
```

--------------------------------

### Paginate through trashed notes in Python

Source: https://github.com/alondmnt/joplin-mcp/blob/main/_autodocs/api-reference/trash-management.md

Use limit and offset parameters to efficiently retrieve large volumes of trashed notes. Ensure the loop terminates when the result set is exhausted.

```python
# Paginate through 1000+ trashed notes
page_size = 100
page = 0

while True:
    result = await find_notes(
        query="*",
        trash=True,
        limit=page_size,
        offset=page * page_size
    )
    # Process results...
    # Stop when fewer than page_size results returned
    if "TOTAL_ITEMS: 0" in result or page_size not in result:
        break
    page += 1
```