Skip to main content
Glama
johnsarie27

joplin-mcp

by johnsarie27
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

joplin-mcp

Release CodeQL Python 3.10+ License: MIT

A minimal MCP server for Joplin, built with FastMCP. Talks to Joplin's local Web Clipper REST API.

Contents

Related MCP server: Joplin MCP Server

Tools

Tool

Description

search_notes(query, limit=20)

Full-text search

get_note(note_id)

Fetch a note's full content

create_note(title, body, notebook_id)

Create a new note

update_note(note_id, title=None, body=None)

Edit an existing note

delete_note(note_id)

Delete a note (moves it to Joplin's trash)

complete_todo(note_id, completed=True)

Mark a to-do note complete or incomplete

list_notes_in_notebook(notebook_id, limit=20)

Browse a notebook's notes without a search query

list_notebooks()

List notebooks, to get a notebook_id for create_note

create_notebook(title, parent_id=None)

Create a notebook, at the root or nested inside another

list_tags()

List tags, to get a tag_id for get_notes_by_tag

get_notes_by_tag(tag_id, limit=20)

List notes with a given tag

Setup

  1. In Joplin Desktop: Tools > Options > Web Clipper, enable the service, copy the auth token shown there.

  2. Install uv if you don't have it.

  3. Copy config.example.json to config.json at the repo root (already gitignored, so it won't be committed) and fill in:

    {
  "token": "paste-your-token-here",
  "host": "localhost",
  "port": "41184",
  "notebooks": [
    {"id": "notebook-id-or-name", "access": "write"},
    {"id": "another-notebook-id-or-name", "access": "read"}
  ]
}

    host/port are optional and default to localhost/41184. See Access control below for the notebooks list.

Running it

No manual pip install needed — uv run resolves and caches dependencies on first run.

uv run --directory /path/to/joplin-mcp joplin-mcp-server

This looks for config.json in the working directory (which --directory sets to the repo). To keep the config file somewhere else, set JOPLIN_CONFIG to its path:

JOPLIN_CONFIG=/path/to/config.json uv run --directory /path/to/joplin-mcp joplin-mcp-server

Wiring into an MCP client

Both approaches below point at the repo directory, which is where config.json lives — one source of truth for secrets and access config.

Claude Code

claude mcp add joplin -s user -- uv run --directory /path/to/joplin-mcp joplin-mcp-server

-s user registers it at user scope, so it's available in every Claude Code session, not just this repo. Verify with claude mcp get joplin; remove with claude mcp remove joplin -s user.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), adding:

{
  "mcpServers": {
    "joplin": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/joplin-mcp", "joplin-mcp-server"]
    }
  }
}

Fully quit and restart Claude Desktop afterward — it only picks up config changes on launch. This is the schema documented at support.claude.com and modelcontextprotocol.io. Some Claude Desktop builds manage MCP servers through a Settings UI (Extensions/Connectors) instead of this file directly — check there first if the file on disk doesn't have an mcpServers key already.

Using uvx instead (no local checkout needed)

uv run --directory ... (above) operates on a project already cloned to disk — it needs a working copy of this repo, its pyproject.toml, and its lockfile at that path. uvx (short for uv tool run) is different: it fetches the package straight from git into uv's own cache and runs it in an ephemeral environment, so the machine running the MCP client doesn't need a local clone at all — just a config.json and JOPLIN_CONFIG pointing at it.

uvx --from git+https://github.com/johnsarie27/joplin-mcp@<ref> joplin-mcp-server

<ref> can be a branch (e.g. main) or a commit SHA. A branch ref is re-resolved to whatever the current tip commit is on every launch (a network round-trip, and a fresh dependency resolve/build whenever that tip changes) — convenient while iterating, but it means the running server can change without you touching either client config. Pinning <ref> to a specific commit SHA, per the SHA-pinning convention, freezes both the code and its resolved dependency versions until you deliberately bump the pin — prefer this once the repo's been stable through some real usage.

Since there's no local checkout in this mode, set JOPLIN_CONFIG to an absolute path so config.json can still be found. Swap the command/args in whichever client config above to uvx/--from git+... instead of uv/run --directory ..., and add the JOPLIN_CONFIG env var:

claude mcp add joplin -s user -e JOPLIN_CONFIG=/path/to/config.json -- uvx --from git+https://github.com/johnsarie27/joplin-mcp@<ref> joplin-mcp-server
{
  "mcpServers": {
    "joplin": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/johnsarie27/joplin-mcp@<ref>", "joplin-mcp-server"],
      "env": {
        "JOPLIN_CONFIG": "/path/to/config.json"
      }
    }
  }
}

Release tags (v<major>.<minor>.<patch>) are also valid refs — see Releasing in CONTRIBUTING.md for how they're cut. Use one as <ref> when pinning uvx --from git+...@<ref> above.

Tip: you can run the server standalone and call each tool manually before wiring it into a client — see Testing changes in CONTRIBUTING.md.

Access control

search_notes, get_note, create_note, update_note, delete_note, complete_todo, list_notes_in_notebook, get_notes_by_tag, and create_notebook are scoped by the notebooks list in config.json. Each entry is:

{"id": "notebook-id-or-name", "access": "read"}

access is "read" (default if omitted) or "write" (implies read). search_notes/get_note/list_notes_in_notebook/get_notes_by_tag require read; create_note/update_note/delete_note/complete_todo require write on the relevant notebook. create_notebook follows the same rule when nesting inside an existing notebook (parent_id set) — it requires write on that parent, same as create_note. Creating a notebook at the root (parent_id omitted) is different: it isn't scoped to any existing notebook id, so it's governed by the $root sentinel instead — see below. This is fail-closed: if notebooks is missing, empty, or none of its entries grant applicable access, these tools refuse to operate. list_notebooks and list_tags are unaffected since they only return notebook/tag metadata, not note content, and double as the way to find the ids/names to pass to the scoped tools above.

Name matching is case-insensitive (Tech, tech, and TECH are equivalent) and resolved against the live notebook list on each call, so a rename takes effect immediately. Since Joplin doesn't require notebook names to be unique (nested notebooks can share a title), a name that matches more than one notebook grants that access level to all of them — use the notebook id instead (from list_notebooks) if you need to scope to just one of several same-named notebooks.

Use {"id": "*", "access": "read"} or {"id": "*", "access": "write"} to grant that access level to all notebooks. This is a deliberate opt-in, distinct from leaving notebooks empty.

Use the reserved id "$root" to grant permission to create notebooks at the root of the notebook tree — i.e. create_notebook calls that omit parent_id:

{"id": "$root", "access": "write"}

This is a separate, narrower opt-in than blanket write access: it lets a config that only grants write on specific notebooks (e.g. Tech) also create new top-level notebooks, without granting write access to every existing notebook. {"id": "*", "access": "write"} already implies it, so you only need $root if you want root-level creation without full write access to everything else. $root only has meaning with access: "write"; an entry for it with access: "read" (or omitted) is a no-op, since there's nothing to read at the root. It also never grants read or write access to any real notebook — it's checked before name/id resolution runs, so it can't collide with an actual notebook, even one literally titled $root.

Two edge cases worth knowing about $root: matching is exact and case-sensitive (unlike the case-insensitive name matching above), so a typo like "$Root" won't be recognized as the sentinel — it silently falls through to normal name/id resolution and matches nothing, rather than raising an error. And because $root is intercepted before name/id resolution runs, a real notebook titled $root can no longer be granted access by name in the notebooks list — use its id instead (from list_notebooks), same as with any other name collision.

Out-of-scope access raises a NotebookAccessError with a message naming the notebook, distinct from a JoplinError (an actual Joplin API failure).

Notes on this build

  • Requires Joplin Desktop running with the Web Clipper service enabled (i.e. Joplin itself must be open — this doesn't run Joplin headlessly).

  • host / port in config.json override the defaults (localhost / 41184) if needed.

  • Errors from the Joplin API surface as JoplinError with the raw status/body — check these first if a tool call fails.

References

Related projects

Contributing

See CONTRIBUTING.md for development setup, testing, and the release process.

Available Tools

11 tools
complete_todoB

Mark a to-do note complete or incomplete. Fails if the note isn't a to-do.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYes
completedNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full burden. It discloses the failure condition (fails if not a to-do) which is a key behavior. However, it does not mention idempotency, authorization requirements, or side effects (e.g., whether changing completed to false undoes completion). Basic transparency, but gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise (one sentence) and front-loaded with the main action. Includes a critical failure condition. However, it could be structured slightly better (e.g., separating parameter info), but no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 2 parameters, no annotations, and an output schema (not shown), the description lacks return value info, idempotency, and prerequisites. Sibling tool exists but no comparison. The description is too minimal to fully guide correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description does not elaborate on parameters beyond the action. It does not explain that note_id identifies the note or that completed defaults to true. The description adds no semantic value over the raw schema, leaving the agent to guess parameter roles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb (mark), resource (to-do note), and the two states (complete/incomplete). Also mentions failure condition for non-to-do notes, which distinguishes it from a generic update tool. Sibling get_note is for retrieval, so purpose is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for toggling completion status but provides no explicit when-to-use or when-not-to-use guidance. No mention of alternatives or exclusion cases beyond the failure condition. Sibling get_note is not referenced, so the agent must infer context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_noteA

Create a new note in the given notebook. Use list_notebooks to find a notebook_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
titleYes
notebook_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Only states 'Create a new note' which implies non-destructive, but lacks details on side effects, limits, or return behavior. Minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences that efficiently convey the core purpose and a key prerequisite. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple (3 required params, no nested objects) and output schema exists, so completeness is moderate. However, lack of parameter descriptions and behavioral details leaves gaps that the description could fill.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description adds no meaning beyond parameter names. Only mentions notebook_id in context of finding it via list_notebooks. Title and body are left entirely to inference from names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'Create' and resource 'new note in the given notebook'. Distinguishes from sibling tools that perform other operations (delete, get, search, update, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly suggests using list_notebooks to find the required notebook_id, providing clear guidance on a prerequisite. No explicit when-not-to-use, but the tool is self-contained.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_notebookA

Create a new notebook. Omit parent_id to create it at the root of the notebook tree (requires a $root write entry in config, or blanket write access); set parent_id to nest it inside an existing notebook (requires write access to that notebook). Use list_notebooks to find a parent_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes
parent_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the permission requirements for both root and nested creation ('requires a `$root` write entry in config, or blanket write access' and 'requires write access to that notebook'). This is valuable behavioral context beyond the schema. However, it doesn't mention what happens on success (e.g., return value) or potential side effects, but the output schema exists, which mitigates the need to explain return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every clause adds value. It efficiently covers usage, permissions, and alternative tool without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 params, one optional), the description covers the key decision (root vs. nested) and permission requirements. The output schema exists, so return values are covered. It could mention error cases or prerequisites, but the description is largely complete for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the semantics of parent_id in detail (root vs. nested, permission implications) and implicitly explains title as the notebook's name. This adds significant meaning beyond the bare schema, though it doesn't describe title's format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Create a new notebook.' It specifies the two modes of operation (root vs. nested) and distinguishes it from sibling tools like create_note and list_notebooks by focusing on notebook creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use each parameter: omit parent_id for root creation, set it for nesting. It also names the alternative tool (list_notebooks) for finding a parent_id, which helps the agent decide when to use this tool versus others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_noteB

Delete a note by its id. Moves it to Joplin's trash rather than a permanent delete.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states that deletion moves the note to Joplin's trash rather than permanently deleting it. This is a key behavioral disclosure beyond the parameter schema. No annotations are provided, so the description carries full responsibility for transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that front-load the core action ('Delete a note by its id') and then add a crucial nuance (trash vs. permanent delete). No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, the description is mostly sufficient. However, given the presence of sibling tools like 'complete_todo' and 'update_note', it lacks guidance for choosing this tool over those. It also does not explain the return value, but an output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description merely says 'by its id', which adds no insight beyond the parameter name. It does not explain what a valid note_id looks like, how to obtain one, or any constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'delete' and the resource 'note by its id'. This distinguishes it from sibling tools like 'create_note', 'update_note', and 'get_note', which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'complete_todo' for todo notes or 'update_note' for modifications. The description only mentions trash behavior, which is a behavioral trait, not a usage criterion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_noteA

Fetch the full content of a single Joplin note by its id.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates a read-only operation ('fetch') but no annotations are provided. It lacks details on permissions, rate limits, or what 'full content' specifically includes, though an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no extraneous words, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-id tool with an output schema, the description adequately conveys the core action without requiring additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for note_id, and the description only says 'by its id', adding minimal semantic value beyond the parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'fetch' and the resource 'full content of a single Joplin note by its id', distinguishing it from siblings like create_note or update_note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a note_id and want full content, but does not explicitly state when to use this tool versus search_notes or update_note.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_notes_by_tagA

List notes with a given tag. Use list_tags to find a tag_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
tag_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It only states a basic function, omitting details like pagination, sorting, limit behavior, or what happens when no notes match. The limit parameter is not explained, leaving the agent uninformed about result set handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no unnecessary words. The main action is front-loaded, and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, return values need not be described. However, with 2 parameters (1 required), no schema descriptions, and no behavioral details from annotations, the description is somewhat thin. It covers the essential tag_id lookup but lacks information on limit usage, result ordering, or edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should clarify parameter meanings beyond the schema. It mentions tag_id implicitly ('use list_tags to find a tag_id') but does not explain the limit parameter or provide format constraints or examples. The description adds minimal value over the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List notes with a given tag.' It specifies the action (list), resource (notes), and filtering criterion (tag). It also directs to list_tags for tag discovery, differentiating it from sibling tools like list_notes_in_notebook and search_notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage guidance by referencing list_tags to find a tag_id, which is helpful context. However, it does not explicitly state when not to use this tool or mention alternative tools for other scenarios, missing an opportunity to guide against misuse.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_notebooksA

List all Joplin notebooks (folders) with their ids, for use with create_note.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool lists all notebooks with their ids, which is accurate and non-destructive. However, it does not disclose any behavioral traits such as pagination, ordering, or rate limits. For a zero-parameter tool, the description is minimal but adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the essential purpose and a hint of usage. No wasted words—every part contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, output schema exists) and the presence of sibling tools, the description is sufficient. It could optionally mention that notebooks are hierarchical, but the output schema likely covers return fields. Overall, it is complete enough for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters with 100% coverage via description (the schema itself is empty). There is no need for additional parameter semantics. The baseline for no parameters is 4, and the description does not need to add more.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists all Joplin notebooks with their ids, providing the specific verb 'list' and resource 'notebooks'. It also hints at a primary use case (for create_note). Among sibling tools, no other tool lists notebooks, so it is well-distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions a use case ('for use with create_note'), giving context on when to use it. However, it does not explicitly state when not to use it or compare to alternatives like search_notes or list_notes_in_notebook. The guidance is clear but could be more complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_notes_in_notebookA

List notes in a notebook without a search query. Use list_notebooks to find a notebook_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
notebook_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It indicates a read operation (list) but does not confirm side effects, auth requirements, error handling, or pagination beyond the limit parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no redundant information. The first sentence states the purpose, the second provides a helpful pointer. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the need to describe return values is reduced. The description covers the core purpose and a prerequisite (getting notebook_id). It lacks notes on ordering or error cases, but is adequate for a simple list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It explains notebook_id context ('Use list_notebooks to find a notebook_id') but provides no details on the 'limit' parameter. Partial compensation for one of two parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List notes in a notebook') and distinguishes from search tools by specifying 'without a search query'. It also provides a pointer to list_notebooks for obtaining the notebook_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (no search query) and suggests using list_notebooks to find the notebook_id. However, it does not explicitly state when not to use this tool versus alternatives like search_notes or other note tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tagsA

List all Joplin tags with their ids, for use with get_notes_by_tag.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states what the tool does (list tags) but does not disclose behavioral traits like whether it is read-only, any authorization requirements, or side effects. The agent must infer safety from context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with 10 words, no filler. It is perfectly concise and front-loaded with the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless tool with an output schema, the description is complete: it states what is listed (tags with ids) and why it is useful (for use with 'get_notes_by_tag'). No additional information is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%. The description does not need to add parameter semantics, and it appropriately clarifies the output context (tags with ids). Baseline 4 for 0 parameters is justified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List all Joplin tags') and the resource ('tags with their ids'). It also specifies the intended usage context ('for use with get_notes_by_tag'), distinguishing it from sibling tools like 'get_notes_by_tag' itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: to retrieve tag ids for use with 'get_notes_by_tag'. It provides clear context but does not explicitly state when not to use it or mention alternatives, though the sibling list hints at other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_notesC

Search Joplin notes by keyword. Returns matching note titles and ids.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It states the output but does not disclose behavioral traits such as case sensitivity, search scope (title vs. body), pagination, sorting, or read-only nature. The description is too minimal for an agent to infer safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with two sentences covering purpose and output. However, it could be improved by adding a brief note on parameter usage without becoming verbose. Currently it is efficient but lacks depth.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the large set of sibling tools and the absence of parameter descriptions in the schema, the description is insufficient. It does not differentiate this search from other retrieval tools, nor does it explain behavior beyond basic output. An output schema exists but is not described in the tool description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% parameter description coverage. The tool description only mentions 'by keyword', which relates to the 'query' parameter, but does not explain the 'limit' parameter or its default value. The description adds some meaning for query but is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool searches Joplin notes by keyword and returns note titles and IDs. This distinguishes it from sibling tools like get_note (single note) or list_notes_in_notebook (filtered by notebook).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. For example, it does not clarify that this tool is for keyword-based search while filtering by notebook or tag requires other tools. No exclusions or context are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_noteA

Update an existing note's title and/or body. Only provided fields are changed.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNo
titleNo
note_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Only states it updates fields; doesn't disclose side effects, permissions, idempotency, or behavior on missing note_id. Lacks critical behavioral context for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, direct sentences. Front-loaded with verb and resource, then clarifies partial update. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 3-param tool with output schema, the description is adequate but lacks details on error handling, return value, or prerequisites. Not fully complete given the context signals.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds meaning by explaining partial update semantics for title and body, but doesn't describe note_id or parameter types beyond high-level intent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Update' and resource 'existing note', specifies which fields are affected ('title and/or body'), and distinguishes from siblings like create_note and delete_note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicitly indicates when to use: to modify an existing note's content. The phrase 'Only provided fields are changed' guides on partial updates, but no explicit when-not or alternatives mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation4/5

Tools are mostly distinct: search_notes vs list_notes_in_notebook vs get_notes_by_tag have different retrieval modes, and CRUD operations are clear. However, some potential overlap exists between search_notes (which returns titles/ids) and list_notes_in_notebook (which lists notes in a notebook) when an agent is simply looking for notes in a notebook without a query. Also, complete_todo is a niche mutation that could be confused with update_note since todo status is part of note content, though the description clarifies it.

Naming Consistency4/5

Mostly consistent verb_noun snake_case pattern: list_notes_in_notebook, create_notebook, get_notes_by_tag. Minor deviations: 'search_notes' versus 'list_notes_in_notebook' uses different verbs for similar listing operations, and 'complete_todo' uses 'complete' rather than a more consistent 'update_todo_status'. Still readable and largely predictable.

Tool Count4/5

11 tools is within the ideal 3-15 range and aligns with Joplin's core domains: notes (CRUD + search), notebooks (list/create), tags (list/get notes by tag), and todos (complete). No obvious redundancy, though tagging operations are a bit limited (no create/delete/assign tag tools), which makes the count feel slightly incomplete for tags but appropriate overall.

Completeness3/5

Covers the main note lifecycle (create, get, update, delete), notebook creation and listing, and note retrieval by notebook/tag/search. However, significant gaps exist: no notebook update or delete, no tag creation/deletion/assignment, no move/copy note between notebooks, and no ability to create or edit to-do details beyond marking complete. The server handles the note CRUD core but misses expected notebook and tag management operations.

Maintenance

ActivityActive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Jopmcp

    JPFrancoia
    F
    license
    Not graded
    quality
    D
    maintenance
    A MCP server for Joplin note-taking application that enables interaction with Joplin notes through the web clipper API, supporting notebook hierarchy and running in Docker.

  • Joplin MCP Server

    Darkflib
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides standardized tools for querying and retrieving notes from Joplin personal knowledge manager through its API, enabling AI assistants to access and reference personal notes contextually.
    9
    MIT

  • joplin-mcp

    songtianlun
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables interaction with Joplin notes through MCP, allowing searching, creating, updating, and deleting notes via the Joplin Web Clipper API.
    10
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/johnsarie27/joplin-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server