조플린(Joplin) REST API 외부 연결 가이드: n8n 자동화 연동하기

컴퓨터, 소프트웨어 2026년 9월 24일

조플린(Joplin) 노트 앱

개인적으로 노트 앱 중에서 가장 좋아하는 앱이 조플린입니다. 노션이나 옵시디언은 안 쓴 지 오래되었습니다. 조플린의 부족한 점을 보완하는 앱을 직접 만들어 쓰다 보니 다시는 다른 노트 앱으로 돌아가지 못할 것 같습니다.

옵시디언을 많은 사람들이 사용하는 이유 중 하나는 노트를 .md 파일 자체로 저장하기 때문에 터미널 명령(AI나 외부 앱)으로 접근하기 쉽다는 점일 것입니다.

저 같은 경우는 대부분의 자동화 작업을 서버를 통해서 처리하기 때문에 .md 파일로 처리하는 것보다 DB+API 형식을 선호합니다. n8n 같은 자동화 앱이 내 컴퓨터나 스마트폰이 꺼져 있어도 노트 데이터에 접근할 수 있어야 하기 때문입니다.

물론 옵시디언도 클라우드에 올려두고 로컬을 거치지 않은 채 서버와 클라우드 간에 .md 파일을 읽고 쓰도록 만들 수 있습니다. 하지만 DB 방식이 아니어서 데이터 조회 성능이 마음에 들지 않고, 어차피 API는 직접 구축해야 합니다.

조플린 Data API의 단점

조플린은 Web Clipper 경로를 통한 Data API를 지원합니다. 외부 앱이 HTTP 요청으로 노트를 읽고 쓸 수 있는 기능입니다. 요즘 같은 AI, 자동화 시대에 필수적인 기능이죠. 그런데 치명적인 단점이 있습니다. listen IP:port가 127.0.0.1:41184로 고정되어 있다는 점입니다. 이 때문에 현재 내 컴퓨터에 설치된 Data API에만 접근할 수 있습니다.

📘

조플린 서버(노트 데이터를 PostgreSQL에 보관)에서 노트를 직접 읽고 쓸 수 있는 API를 제공하면 좋겠지만, 아쉽게도 이 기능은 없습니다.

노트를 읽는 것은 PostgREST를 이용해 쉽게 구현할 수 있습니다. 하지만 노트를 쓰는 것은 고려해야 할 점이 많습니다. 단순히 노트가 저장되는 테이블에 데이터를 직접 추가하면 데이터가 오염될 위험이 있습니다.

조플린 터미널 앱을 이용한 우회

다행히 조플린은 GUI 앱뿐만 아니라 CLI 환경에서 사용할 수 있는 터미널 앱도 제공합니다. 조플린 터미널 앱(Joplin Terminal App)은 Node.js를 사용할 수 있는 환경이라면 어디서나 동작합니다. Data API 역시 제공됩니다(joplin server start 명령어로 실행).

따라서 서버에 조플린 터미널 앱을 설치하고 nginx나 socat을 이용해 0.0.0.0 바인딩을 통해 외부 접근이 가능하도록 라우팅하면 됩니다.

💡

Joplin Server(DB) ↔ Joplin Terminal App + socat(0.0.0.0) ↔ 외부 앱

우회하는 김에 Sync 기능도 추가

조플린의 Data API에는 또 하나의 단점이 있습니다. Sync(동기화) 명령이 없다는 점입니다. 터미널에서 직접 동기화 명령(joplin sync)을 실행하거나 설정된 동기화 주기를 기다려야 합니다. 그래서 만드는 김에 동기화 명령도 API를 통해 즉시 실행할 수 있도록 기능을 추가했습니다.

만드는 김에 Header 인증도 추가

조플린 Data API는 기본적으로 외부 접근이 차단된 로컬 환경용이므로 URL 쿼리 스트링 방식으로 인증합니다. 다음과 같은 형식입니다.

curl http://localhost:41184/notes?token=ABCD123ABCD123ABCD123ABCD123ABCD123

로컬 환경에서만 접근한다면 이 방식도 문제가 없습니다. 하지만 제가 만들려는 방식은 외부 서버에서 접근해야 하므로, 이러한 URL 쿼리 방식은 토큰이 노출되기 쉽습니다.

그래서 다음과 같이 Authorization 헤더 방식으로 인증하도록 변경했습니다.

curl "http://127.0.0.1:41185/notes" \
  -H "Authorization: Bearer ABCD123ABCD123ABCD123ABCD123ABCD123"

🔥

토큰을 URL 쿼리에 포함하는 방식은 외부 접근용으로 사용하기에 보안상 위험합니다.

도커(Docker) 이미지로 작성

원래는 도커파일(Dockerfile) 내부에 필요한 환경만 구축하고 gateway.sh를 실행하는 방식으로 만들어 개인적으로 사용했습니다. 그러다 도커 허브에 한 번 배포해 볼까? 하는 마음으로 정리하여 배포해 보았습니다.

⚠️

언제나 느끼지만 혼자 쓰려고 만드는 것과 배포용을 만드는 것의 난이도 차이는 큽니다.

저장소

배포용으로 다시 만들면서 github 저장소도 public으로 다시 만들고, 도커 허브 저장소도 만들었습니다. 가급적 적은 용량으로 동작하도록 여러 실험을 해 봤습니다.

GitHub: https://github.com/bonik21/joplin-terminal-api
Docker Hub: https://hub.docker.com/r/bonik21/joplin-terminal-api

📘

아무런 대가 없이 오픈소스를 개발하고 배포하는 개발자분들을 진심으로 존경합니다.

joplin-terminal-api

프로젝트 이름을 joplin-terminal-api로 정하고 도커 허브에 배포를 완료했습니다.

배포 후 생각해 보니 이름을 너무 단순하게 지어서 조플린 공식 개발진에게 혼동을 주거나 누가 되는 것은 아닌지 우려되기도 했습니다. 추후 공식 기능이 추가된다면 명칭이 겹칠 수도 있으니까요.

그런데 배포한 지 10분도 되지 않아 다운로드 수가 약 120회를 기록했습니다. 실제 사용자가 다운로드했다기보다는 봇이나 크롤러의 동작이었던 것으로 보입니다. 어쨌든 이미 다운로드 기록이 발생했으므로 혼란을 줄이기 위해 이름은 그대로 유지하기로 했습니다.

이런 분들에게 추천합니다.

REST API(HTTP/HTTPS)를 이용해 외부에서 조플린 노트 데이터에 접근해야 하는 분 (예: n8n 자동화, 외부 AI 서버의 노트 데이터 조회 등)
조플린 노트를 n8n 등 자동화 도구와 연동하려는 분
조플린 노트를 데이터베이스처럼 활용하고 싶은 분 (다른 도구에서 조플린 노트 읽기/쓰기)