Joplin

Manage Joplin notes via Server API - create, read, edit, search notes, notebooks, todos, and kanban boards

Security Scan

The skill's code, instructions, and required files are consistent with a Joplin Server API client — it requires node and a local config file, and its behavior (reading/writing that config, calling a user-provided Joplin Server URL, optionally using the op CLI) matches the stated purpose.

Purpose & Capability

Name/description, required binaries (node), declared config path (~/.joplin-server-config), included JS client (scripts/joplin-server-api.js), and SKILL.md commands all align: the skill needs to run a bundled Node script against a user-provided Joplin Server URL and authenticate with an email/password. Nothing requested appears unrelated to the stated purpose.

Instruction Scope

The SKILL.md instructs the agent to run bash commands and the bundled node script for all operations (ping, login, list-notes, add-note, etc). It also instructs retrieving secrets from 1Password (via op read) or creating a local config file. This is within scope for a client, but it gives the skill runtime access to the user's home directory (reads/writes ~/.joplin-server-config and ~/.joplin-session) and to any 1Password items the user allows — the agent will be executing those commands directly, so the user should be comfortable with that level of local access.

Install Mechanism

There is no install spec; this is instruction + bundled code executed by node. No network downloads or external installers are performed by the skill itself. The README suggests an optional git clone, but the packaged skill already contains the JS client. No suspicious install URLs or archive extraction are present.

Credentials

The skill does not request unrelated environment variables; it reads JOPLIN_* from environment or ~/.joplin-server-config. It optionally uses the op CLI to pull secrets from 1Password. However, it will store the Joplin password in plaintext in ~/.joplin-server-config (and maintains a session file ~/.joplin-session). These behaviors are proportional for a password-based client but are sensitive — users should be aware credentials are written locally and can choose to manage them differently (e.g., use a dedicated account, limit permissions, or remove the file after use).

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It will create/modify two files under the user's home directory (~/.joplin-server-config and ~/.joplin-session), and may persist cookies/session info there. This is normal for a client but is persistent filesystem access and should be considered by the user.

Assessment

This skill appears to do what it says: it runs a bundled Node client to talk to a Joplin Server URL you provide. Before installing, confirm you trust the skill source (the source is listed as unknown in the registry). Understand the practical implications: the agent will execute Bash/node commands, will read and write ~/.joplin-server-config (which will contain your JOPLIN_PASSWORD in plaintext) and ~/.joplin-session (session cookies). If you opt to use 1Password, the skill uses the op CLI to read the specified vault/item and will write those credentials into the local config file. Recommended precautions: review the included scripts/joplin-server-api.js yourself (it’s bundled) to confirm no unexpected endpoints; use a dedicated or limited-permission account for the Joplin Server if possible; do not enable JOPLIN_SKIP_TLS_VERIFY unless absolutely necessary; and remove or rotate credentials after use if you are concerned about storing plaintext passwords locally.

Joplin Server API Skill

Manage Joplin notes via the Joplin Server REST API (based on joppy).

CRITICAL: Always Execute Commands

NEVER assume or hallucinate results. You MUST:

1. Always run the actual commands using the Bash tool
2. Check for errors in JSON responses - report any errors to the user
3. Show real data from the API responses
4. If config is missing, offer to retrieve from 1Password or create manually

Setup

Credentials can be configured in two ways:

Option A: Config File

Create ~/.joplin-server-config:

JOPLIN_SERVER_URL=https://your-joplin-server.com
JOPLIN_EMAIL=[e-mail]
JOPLIN_PASSWORD=your-password
# Optional: skip TLS verification for self-signed certificates (security risk!)
# JOPLIN_SKIP_TLS_VERIFY=true

Option B: 1Password

If user prefers 1Password, retrieve credentials and create the config:

# Get credentials from 1Password (adjust vault/item name as needed)
JOPLIN_URL=$(op read "op://Private/Joplin Server/url" 2>/dev/null)
JOPLIN_EMAIL=$(op read "op://Private/Joplin Server/username" 2>/dev/null)
JOPLIN_PASS=$(op read "op://Private/Joplin Server/password" 2>/dev/null)

# Write config file
cat > ~/.joplin-server-config << EOF
JOPLIN_SERVER_URL=$JOPLIN_URL
JOPLIN_EMAIL=$JOPLIN_EMAIL
JOPLIN_PASSWORD=$JOPLIN_PASS
EOF
chmod 600 ~/.joplin-server-config

Ask user for their 1Password vault name and item name if different from "Private/Joplin Server".

Client Usage

All commands use the bundled JavaScript client:

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js <command> [args...]

Available Commands

Command	Description
ping	Health check (no auth required)
login	Authenticate and verify connection
list-notebooks	List all notebooks
list-notes	List all notes
get-note <id>	Get note content
add-notebook <title>	Create a new notebook
add-note <title> [parent_id] [body]	Create a new note
modify-note <id> <field> <value>	Modify a note field
delete-note <id>	Delete a note
search <query>	Search notes by title/content

Response Format

All commands return JSON. Errors include an error field:

{"id": "abc123", "title": "My Note"}   // Success
{"ok": false, "error": "..."}          // Failure

Workflow: First Time Setup

When user first invokes this skill:

# Step 1: Check if config exists
cat ~/.joplin-server-config 2>/dev/null || echo "CONFIG_MISSING"

# Step 2: If config exists, test connection
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js ping

If config is missing, ask user which setup method they prefer:

1. 1Password - Ask for vault/item name, then run:

   JOPLIN_URL=$(op read "op://VAULT/ITEM/url")
   JOPLIN_EMAIL=$(op read "op://VAULT/ITEM/username")
   JOPLIN_PASS=$(op read "op://VAULT/ITEM/password")
   cat > ~/.joplin-server-config << EOF
   JOPLIN_SERVER_URL=$JOPLIN_URL
   JOPLIN_EMAIL=$JOPLIN_EMAIL
   JOPLIN_PASSWORD=$JOPLIN_PASS
   EOF
   chmod 600 ~/.joplin-server-config
   

2. Manual - User creates ~/.joplin-server-config with:

   JOPLIN_SERVER_URL=https://your-server.com
   JOPLIN_EMAIL=your-email
   JOPLIN_PASSWORD=your-password
   

Common Operations

List Notebooks

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js list-notebooks

List All Notes

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js list-notes

Read a Note

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js get-note <note_id>

Create a Notebook

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-notebook "My Notebook"

Create a Note

# Basic note
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-note "My Note Title"

# Note in a specific notebook
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-note "My Note Title" <notebook_id>

# Note with body content
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-note "My Note Title" <notebook_id> "Note body here"

Modify a Note

# Update title
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js modify-note <note_id> title "New Title"

# Update body
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js modify-note <note_id> body "New body content"

Search Notes

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js search "search term"

Delete a Note

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js delete-note <note_id>

Sync Lock

The API client automatically handles Joplin's sync lock protocol:

• Acquires a sync lock before write operations (add, modify, delete)
• Releases the lock after the operation completes
• Read operations (list, get, search) don't require locks

Item Types

Type	Value	Description
Note	1	Markdown notes
Folder	2	Notebooks
Resource	4	Attachments
Tag	5	Tags
NoteTag	6	Note-tag links

Note Content Format

Notes are returned as objects with these fields:

{
  "id": "abc123def456",
  "parent_id": "parent-folder-uuid",
  "title": "My Note Title",
  "body": "Note content in markdown...",
  "created_time": "2024-01-15T10:30:00.000Z",
  "updated_time": "2024-01-15T10:30:00.000Z",
  "type_": "1",
  "markup_language": "1"
}

TODOs

All TODOs go into the "TODOs" notebook.

Daily TODOs

Daily planning notes follow this naming format:

TODO#dd.mm.yy <Wd>

Where <Wd> is a 2-letter weekday: Mo, Tu, We, Th, Fr, Sa, Su

Examples:

• TODO#16.03.26 Su (Sunday, March 16, 2026)
• TODO#17.03.26 Mo (Monday, March 17, 2026)

Content format: One checkbox per line for individual tasks:

- [ ] Morning standup
- [ ] Review PR #123
- [ ] Deploy to staging
- [x] Send weekly report

General TODOs

Non-daily TODOs (projects, ideas, recurring tasks) also go in the "TODOs" notebook but:

• Don't follow the TODO#dd.mm.yy naming format
• Each note represents one individual task or topic
• Use descriptive titles like "Fix authentication bug" or "Research caching options"

Kanban Notes (YesYouKan)

When editing kanban-formatted notes:

1. Column headings use # - Keep exact names: # Backlog, # In progress, # Done
2. Task headings use ##
3. Never modify the kanban-settings code block at the end
4. Preserve blank lines exactly as they appear

Error Handling

Error	Meaning
CONFIG_MISSING	No ~/.joplin-server-config file
Authentication failed	Wrong credentials or server unreachable
Request timeout	Server not responding (check URL)
Sync target has exclusive lock	Another client is syncing
404	Item not found

Troubleshooting

If auth fails:

# Test server reachability
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js ping

# Test login
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js login

# Check config file
cat ~/.joplin-server-config