Joplin MCP

MCP 서버로, Joplin 노트 컬렉션을 도구 세트로 노출하며 Cloudflare Workers에서 상태 저장 에이전트로 실행됩니다. 배포된 엔드포인트에 MCP 클라이언트(Claude 등)를 연결하면 노트북과 노트를 탐색하고, 사용자 자신의 Joplin 인스턴스에서 직접 노트와 노트북을 생성/수정/삭제할 수 있습니다.

작동 방식

모든 도구 호출은 실행 중인 인스턴스의 Joplin Data API로 직접 전달됩니다. 그 사이에 인덱스나 캐시는 없습니다. Joplin Data API 자체는 공개 인터넷에 노출되지 않습니다. Worker는 Cloudflare Tunnel을 통해 Workers VPC Service 바인딩으로 비공개적으로 접근합니다.

MCP client ──HTTP/SSE──► Worker (/mcp) ──► JoplinMCP (Durable Object)
                                                  │
                          JoplinClient ──► JOPLIN_VPC (Workers VPC Service)
                                                  │
                          Cloudflare Tunnel ──► Joplin Data API (LAN-only)

JoplinMCP는 Durable Object에서 호스팅되는 McpAgent입니다.

Related MCP server: Capacities MCP Worker

도구

노트나 노트북을 인자로 받는 모든 도구는 32자리 16진수 ID뿐만 아니라 이름도 그대로 받아들이므로, 호출하는 에이전트가 ID를 찾기 위해 왕복 요청을 할 필요가 없습니다. 이름은 퍼지 매칭됩니다(대소문자, 악센트, 문장 부호, 단어 순서는 모두 무시됩니다). 이름이 실제로 모호한 경우 도구는 추측하는 대신 ID가 포함된 후보들을 반환합니다.

휴지통에 있는 노트와 노트북은 모든 결과에서 제외됩니다 — 목록, 검색, 직접 읽기 모두 마찬가지입니다.

왕복 줄이기

도구 표면은 에이전트가 가능한 한 적은 호출로 원하는 노트에 도달할 수 있도록 설계되었습니다. 이름으로 노트를 읽는 것은 세 번 대신 한 번의 호출로 가능합니다:

list_notebooks → list_notes → get_note      ⟶   get_note { note: "grocery list" }

그리고 줄을 추가하는 것도 두 번 대신 한 번의 호출로 가능합니다. append가 서버 측에서 읽기-수정-쓰기를 수행하기 때문입니다:

get_note → update_note { body: <whole note> }  ⟶  update_note { note: "grocery list", append: "- milk" }

이름 확인은 Joplin 자체 검색 인덱스를 통해 이루어지므로 일반적으로 API 호출 한 번만 소요됩니다. 로컬 제목 인덱스는 검색 결과가 없을 때만(오타, 또는 전체 텍스트 인덱스가 제목을 이상하게 토큰화하는 경우) 구축됩니다. 노트북 목록은 Durable Object에 캐시되므로 노트북 이름 확인은 대개 무료입니다.

설정

npm install

배포 전에 Joplin Data API가 Cloudflare Tunnel에서 도달 가능해야 하며, Workers VPC Service로 등록되어야 합니다:

npx wrangler vpc service create joplin-data-api \
  --type http \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --hostname <JOPLIN_HOST_ON_YOUR_LAN> \
  --http-port <JOPLIN_PORT>

그런 다음 결과 서비스 ID를 wrangler.jsonc에 바인딩합니다:

"vpc_services": [
  { "binding": "JOPLIN_VPC", "service_id": "<service-id-from-above>", "remote": true }
]

JOPLIN_API_TOKEN(Joplin Data API 토큰)은 일반 Wrangler 시크릿이 아니라 Cloudflare의 Secrets Store에서 읽습니다. 계정당 한 번 생성하면 Workers 전체에서 재사용할 수 있습니다:

wrangler secrets-store secret create <store-id> \
  --name joplin-token --scopes workers --remote

wrangler.jsonc는 그런 다음 secrets_store_secrets를 통해 이를 바인딩합니다:

"secrets_store_secrets": [
  { "binding": "JOPLIN_API_TOKEN", "store_id": "<store-id>", "secret_name": "joplin-token" }
]

로컬 개발의 경우 같은 이름의 로컬 전용 시크릿을 생성하고(--remote 생략) wrangler dev가 읽을 수 있도록 합니다.

기본 노트북

노트북을 인자로 받는 도구는 wrangler.jsonc의 JOPLIN_DEFAULT_NOTEBOOK 변수로 지정된 노트북으로 대체됩니다(기본값은 "Default"). 새 노트가 들어가야 할 노트북을 가리키도록 설정하세요. 해당 이름의 노트북이 없으면 도구는 임의로 선택하는 대신 그 사실을 알려줍니다.

전체 아키텍처와 바인딩 참조는 CLAUDE.md를 참조하세요.

개발

npm run dev         # wrangler dev — local development with hot reload
npm run test        # vitest run
npm run typecheck   # tsc --noEmit

배포

npm run deploy

또는 이 저장소를 Cloudflare Worker에 연결하여 git 기반 배포를 사용할 수 있습니다. 어느 쪽이든 joplin-token 시크릿은 계정의 Secrets Store에 존재해야 합니다 — 저장소에 저장되는 일은 없습니다.

스택

• Cloudflare Workers + Durable Objects(SQLite 기반)

• Cloudflare Agents SDK(agents/mcp)

• MCP TypeScript SDK

• TypeScript, 도구 입력 스키마용 Zod, Vitest