Metadata-Version: 2.4
Name: second-brain-joplin
Version: 0.2.0
Summary: MCP server that connects Claude Code (and other MCP clients) to your Joplin knowledge base
Project-URL: Homepage, https://github.com/jomkz/second-brain-joplin
Project-URL: Repository, https://github.com/jomkz/second-brain-joplin
Project-URL: Issues, https://github.com/jomkz/second-brain-joplin/issues
License: MIT
License-File: LICENSE
Keywords: ai,claude,joplin,knowledge-base,mcp,second-brain
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastmcp<4,>=3
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Requires-Dist: python-dotenv>=1.0
Provides-Extra: test
Requires-Dist: mypy>=1.11; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# second-brain-joplin

[![CI](https://github.com/jomkz/second-brain-joplin/actions/workflows/ci.yml/badge.svg)](https://github.com/jomkz/second-brain-joplin/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/second-brain-joplin)](https://pypi.org/project/second-brain-joplin/)

An MCP server that turns your [Joplin](https://joplinapp.org/) knowledge base into searchable memory for any MCP-capable AI client — Claude Code, Cursor, and others.

Inspired by [second-brain-mcp](https://github.com/noesskeetit/second-brain-mcp) (for Obsidian). This project covers the same use case for Joplin: your AI assistant reads, searches, and files notes directly, without leaving the tool you already use.

> **Status:** Pre-alpha — the four read tools are live; note creation is still stubbed (human-gated write lands in v0.4). See the [roadmap](#roadmap) and open issues.

---

## How it works

Joplin Desktop exposes a local REST API on `localhost:41184` (the Web Clipper service). This server wraps that API as MCP tools, so your AI client can query and update your notes in real time — no export step, no sync lag.

```
Claude Code / Cursor
       │  MCP
       ▼
second-brain-joplin (this server)
       │  HTTP + token
       ▼
Joplin Desktop (localhost:41184)
       │
       ▼
Your notes
```

---

## Prerequisites

- **Joplin Desktop** running with the Web Clipper service enabled:  
  **Tools → Options → Web Clipper → Enable Web Clipper Service**
- **API token** — copy it from the Web Clipper settings panel
- **Python ≥ 3.11** or [`uvx`](https://docs.astral.sh/uv/) (recommended — no install needed)

---

## Quickstart

### Claude Code

```bash
claude mcp add -s user second-brain-joplin \
  -e JOPLIN_API_TOKEN=your-token-here \
  -- uvx second-brain-joplin serve
```

### Other MCP clients

| Setting | Value |
|---|---|
| Command | `uvx second-brain-joplin serve` |
| `JOPLIN_API_TOKEN` | token from Joplin Web Clipper settings |
| `JOPLIN_BASE_URL` | `http://localhost:41184` (default) |

See [docs/install.md](docs/install.md) for per-client setup guides.

---

## MCP Tools

| Tool | Description | Writes? |
|---|---|---|
| `joplin_overview` | List all notebooks with note counts | No |
| `joplin_search` | Keyword search across all notes | No |
| `joplin_read` | Read a note by ID | No |
| `joplin_recent` | Notes modified in the last N days | No |
| `joplin_create` | Create a note (human-gated) | Yes |

> The four read tools query a running Joplin instance as of v0.2. `joplin_create`
> is still stubbed; the human-gated write flow is tracked in the
> [v0.4 milestone](https://github.com/jomkz/second-brain-joplin/milestone/4).

---

## vs. second-brain-mcp (Obsidian)

| | [second-brain-mcp](https://github.com/noesskeetit/second-brain-mcp) | second-brain-joplin |
|---|---|---|
| Note app | Obsidian | Joplin |
| Storage | Plain `.md` files on disk | Joplin REST API |
| Requires app running | No | Yes (Joplin + Web Clipper) |
| Semantic search | Yes (bge-m3) | Planned (v0.3) |
| Write support | Human-gated | Human-gated (v0.4) |
| Install | `uvx second-brain-mcp` | `uvx second-brain-joplin` |

---

## Notebook structure

The [PARA method](https://fortelabs.com/blog/para/) works well with Joplin. See [docs/notebook-structure.md](docs/notebook-structure.md) for a recommended setup.

---

## Roadmap

| Milestone | Theme | Status |
|---|---|---|
| [v0.1 — Bootstrap](https://github.com/jomkz/second-brain-joplin/milestone/1) | Repo, CI, package skeleton | Done |
| [v0.2 — Core Read Tools](https://github.com/jomkz/second-brain-joplin/milestone/2) | All read MCP tools working | Done |
| [v0.3 — Semantic Search](https://github.com/jomkz/second-brain-joplin/milestone/3) | Embedding index, semantic search | Planned |
| [v0.4 — Write Workflow](https://github.com/jomkz/second-brain-joplin/milestone/4) | Human-gated note creation | Planned |
| [v1.0 — Publish](https://github.com/jomkz/second-brain-joplin/milestone/5) | PyPI, full docs, templates | Planned |

---

## Security & privacy

This server keeps your notes local: it talks only to Joplin's Web Clipper REST API on `localhost` and runs on your own machine. Anything an MCP client can read, the connected AI can read — so apply least privilege and don't expose notebooks with credentials or other sensitive data. Note creation is planned as an explicit human-gated flow (v0.4); v0.1 does no silent writes. See [SECURITY.md](SECURITY.md) for details and how to report a vulnerability.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — especially for testing against different Joplin versions and OS platforms.

---

## License

MIT — see [LICENSE](LICENSE).
