joplin-mcp

Go implementation of a Joplin MCP server. It runs locally as a single binary over MCP stdio and talks to the Joplin Web Clipper REST API.

Build

make build

Related MCP server: Joplin MCP Server

Run

With npm:

JOPLIN_TOKEN=your_token npx joplin-mcp

The npm package is a thin launcher around the prebuilt Go binary for the current platform.

JOPLIN_TOKEN=your_token ./joplin-mcp

For local development:

make dev
make dev ARGS="-token your_token -base-url http://localhost:41184"

Options:

./joplin-mcp -token your_token -base-url http://localhost:41184

Token resolution priority:

1. -token

2. JOPLIN_TOKEN environment variable

3. .env file next to the joplin-mcp binary with JOPLIN_TOKEN=...

4. .env file in the current working directory

Available MCP tools:

• search_notes

• get_note

• create_note

• update_note

• delete_note

• import_markdown

npm Release

Pushing a tag in vx.x.x format triggers GitHub Actions to publish the npm package. The package version is derived from the tag by removing the leading v.

git tag v0.1.0
git push origin v0.1.0

To create the npm package locally:

npm pack

npm pack runs make npm-package first and includes prebuilt Go binaries for Linux, macOS, and Windows.

Checks

make test