# 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

```bash
make build
```

## Run

With npm:

```bash
JOPLIN_TOKEN=your_token npx joplin-mcp
```

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

```bash
JOPLIN_TOKEN=your_token ./joplin-mcp
```

For local development:

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

Options:

```bash
./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`.

```bash
git tag v0.1.0
git push origin v0.1.0
```

To create the npm package locally:

```bash
npm pack
```

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

## Checks

```bash
make test
```