Skip to main content
Glama
Agentic-Joplin MCP Server

Agentic-Joplin MCP Server

Agentic-Joplin

npm skills.sh CI License: MIT

Tooling that lets coding agents integrate with Joplin, the open-source note-taking app.

The project has three planned pieces:

Piece

Status

MCP server — wraps Joplin's Data API as Model Context Protocol tools

✅ Published to npm as agentic-joplin

Joplin plugin — in-app plugin for capabilities the Data API can't expose

🔜 planned

Agent skills — skill files teaching agents how to use Joplin effectively

✅ Claude Code + Codex plugin

This repo is an npm-workspaces monorepo; each piece lives under packages/.

MCP server

packages/mcp-server is a from-scratch Model Context Protocol server (TypeScript, stdio transport) that gives an agent full CRUD over Joplin notes, notebooks, tags, and resources, plus search, note revision history, and a connectivity check — 26 tools across 7 groups. It wraps Joplin's local Data API (the REST service exposed by the desktop app's Web Clipper).

Requirements

  • Node.js ≥ 20

  • Joplin desktop running with the Web Clipper service enabled (Options → Web Clipper).

Setup

The server is published to npm as agentic-joplin:

npx -y -p agentic-joplin agentic-joplin-authorize   # one time: click Accept in Joplin; caches a token

Then add it to your MCP client (e.g. Claude Code / Claude Desktop) as a stdio server:

{
  "mcpServers": {
    "joplin": { "command": "npx", "args": ["-y", "agentic-joplin"] }
  }
}

To run from source instead: npm install && npm run build --workspace agentic-joplin, then point the client at node packages/mcp-server/dist/index.js.

Environment variables:

Variable

Required

Default

Description

JOPLIN_TOKEN

no

—

API token from Joplin's Web Clipper settings. Falls back to the token cached in ~/.agentic-joplin/token.json, then to interactive authorization on first request.

JOPLIN_HOST

no

127.0.0.1

Host of the Web Clipper service

JOPLIN_PORT

no

41184

Port of the Web Clipper service

Joplin must be running with Web Clipper enabled for any tool call to succeed.

Tool surface

Notes (create_note, get_note, update_note, delete_note, list_notes), notebooks (get_notebook, list_notebooks, create_notebook, update_notebook, delete_notebook), tags (get_tag, list_tags, create_tag, update_tag, delete_tag, tag_note, untag_note), search (find_notes), resources (attach_resource, get_resource, update_resource, delete_resource, list_note_resources), revisions (list_note_revisions, delete_note_revisions), and ping.

Notes can be created in Markdown (default) or HTML via a format parameter. See packages/mcp-server/README.md for the full per-tool reference and packages/mcp-server/SMOKE_TEST.md for the manual release checklist.

Related MCP server: Joplin Server MCP

Agent skills plugin

packages/plugin is a single plugin — valid for both Claude Code and Codex — that bundles the Joplin MCP server with four agent skills (using-joplin hub plus joplin-capturing-notes, joplin-searching-and-updating, joplin-organizing). See packages/plugin/README.md for install steps on each platform.

The four skills are listed on skills.sh. To install only the four skills, without the plugin bundle, use the skills CLI (Node.js 22.20 or later). It records the source, so npx skills update keeps them current. The skills still need the Joplin MCP server above.

# All four skills, globally
npx skills add sohampatwardhan/Agentic-Joplin -g

# One skill, for chosen agents only
npx skills add sohampatwardhan/Agentic-Joplin -g --skill using-joplin -a claude-code -a codex

# Update later
npx skills update -g

Companion skills for richer notes

Joplin renders Mermaid diagrams and KaTeX math natively. The Joplin skills work on their own, but when these two optional Agent Skills are installed they defer to them for diagrams and formulas:

  • mermaid — picks a diagram type and writes validated Mermaid.

  • katex — writes KaTeX-safe math with Joplin's $ / $$ delimiters.

Install the Joplin skills and both companions together with skills:

npx skills add sohampatwardhan/Agentic-Joplin -g
npx skills add sohampatwardhan/mermaid-skill -g
npx skills add sohampatwardhan/KaTeX-Agent-Skill -g

If a companion is missing, the agent may offer to install it, but only runs the command after you say yes.

Development

npm run build   # type-check + compile all workspaces
npm test        # check skill versions, then run all workspace unit tests (mocked Data API, no Joplin instance needed)
npm run check:skills  # only check that every SKILL.md has a valid SemVer metadata.version

Skill versioning

Each SKILL.md carries a SemVer 2.0.0 version in its frontmatter metadata map (a string-to-string map, so quote the value):

metadata:
  author: sohampatwardhan
  version: "1.0.0"

Bump a skill's version on any change to it:

  • PATCH for wording and fixes.

  • MINOR for new guidance or behaviour.

  • MAJOR for breaking changes, such as renames or removed steps.

CI and npm test fail if any SKILL.md lacks metadata.version or the value isn't valid SemVer.

Design docs live under docs/superpowers/: the design spec and the implementation plan.

License

MIT © Soham Patwardhan

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for Joplin note-taking app, enabling AI to read, search, and modify notes via sandboxed scripts.
      2
      22 npm
      27
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that turns your Joplin notebook into a tool an LLM can actually use — read, search, write, and organize notes, and pull OCR'd text straight out of your screenshots.
      13
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes Joplin's Data API as MCP tools so an LLM can search, read, create, update, delete, and organize notes, notebooks, and tags against a headless Joplin instance, including attachments and tag management.
      1
      MIT