MCP Joplin 서버

Joplin 노트와 통합되는 모델 컨텍스트 프로토콜(MCP) 서버로, AI 클라이언트(예: Perplexity)가 Joplin의 Web Clipper API를 통해 노트북과 노트에 접근하고 조작할 수 있게 합니다.

기능

🔍 검색 기능: 노트 및 노트북 검색
📖 콘텐츠 읽기: 특정 노트의 전체 콘텐츠 가져오기
📝 생성 기능: 새 노트 및 노트북 생성
✏️ 업데이트/편집 기능: 노트 콘텐츠 업데이트, 노트에 내용 추가, 노트북 이름 변경
🗑️ 삭제 기능: 노트 및 노트북 삭제(휴지통 이동 또는 영구 삭제 지원)
🔄 이동 기능: 노트를 다른 노트북으로 이동
📋 목록 기능: 모든 노트북 및 특정 노트북 내의 노트 목록 표시

요구 사항

Joplin 데스크톱 - 설치 및 실행 상태여야 함
Node.js 18+ - MCP 서버 실행에 필요
Web Clipper 활성화 - Joplin에서 Web Clipper 서비스 활성화 필요

설치 및 설정

1. Joplin Web Clipper 활성화

Joplin 데스크톱 애플리케이션 실행
도구(Tools) → 옵션(Options) → Web Clipper로 이동
Web Clipper 서비스 활성화(Enable Web Clipper Service) 체크
표시된 포트 번호(보통 41184) 확인
API 토큰 복사(인증이 필요한 경우)

2. MCP Joplin 서버 설치

# Clone or download this project
cd mcp-joplin

# Install dependencies
npm install

# Compile TypeScript
npm run build

3. 테스트 실행

# Run directly (will auto-detect Joplin service)
npm start

# Or specify port
npm start -- --port 41184

# Or specify token (if needed)
npm start -- --token YOUR_API_TOKEN

# View help
npm start -- --help

4. npx 사용

# Global installation (recommended)
npm install -g .

# Then use anywhere
npx mcp-joplin

# Or run locally
npx . --port 41184

MCP 클라이언트 설정

Perplexity 또는 기타 MCP 클라이언트 설정

MCP 클라이언트 설정 파일에 다음 구성을 추가하세요:

🔐 구성 (API 토큰 필요)

이 MCP 서버가 제대로 작동하려면 Joplin API 토큰이 필요합니다:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

💡 중요: 이 MCP 서버가 제대로 작동하려면 API 토큰이 필수입니다.

Claude 데스크톱 설정 예시

Claude 데스크톱 설정

~/Library/Application Support/Claude/claude_desktop_config.json 파일:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

사용 가능한 MCP 도구

1. get_note_content

특정 노트의 전체 콘텐츠 가져오기

Parameters: noteId (string) - The ID of the note

2. search_notes

노트 검색

Parameters:
- query (string) - Search keywords
- limit (number, optional) - Result limit (default: 20)

3. search_notebooks

노트북 검색

Parameters: query (string) - Search keywords

4. list_notebooks

모든 노트북 목록 표시

Parameters: None

5. list_notes

특정 노트북 내의 노트 목록 표시

Parameters:
- notebookId (string) - The ID of the notebook
- limit (number, optional) - Result limit (default: 50)

5.1. list_sub_notebooks

특정 노트북 내의 하위 노트북 목록 표시

Parameters:
- parentNotebookId (string) - The ID of the parent notebook

6. create_note

새 노트 생성

Parameters:
- title (string) - Note title
- body (string) - Note content (Markdown format)
- notebookId (string, optional) - Target notebook ID

7. create_notebook

새 노트북 생성

Parameters:
- title (string) - Notebook title
- parentId (string, optional) - Parent notebook ID (for sub-notebooks)

8. delete_note

노트 삭제

Parameters:
- noteId (string) - ID of the note to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

9. delete_notebook

노트북 삭제

Parameters:
- notebookId (string) - ID of the notebook to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

10. move_note

노트를 다른 노트북으로 이동

Parameters:
- noteId (string) - ID of the note to move
- targetNotebookId (string) - Target notebook ID

11. update_note

기존 노트의 제목 및/또는 본문 업데이트

Parameters:
- noteId (string) - ID of the note to update
- title (string, optional) - New note title
- body (string, optional) - New note content (full replacement, not a patch)

참고:

title 또는 body 중 하나 이상이 제공되어야 합니다.
노트 콘텐츠를 교체하거나 노트 이름을 변경할 때 사용하세요.

12. append_to_note

기존 노트 끝에 콘텐츠 추가

Parameters:
- noteId (string) - ID of the note to append to
- content (string) - Content to append
- separator (string, optional) - Separator inserted before appended content (default: "\n\n")

참고:

로그, 회의록, 보충 정보 또는 테스트 결과에 사용하세요.
기존 본문을 교체하지 않고 내용을 추가하려는 경우 update_note보다 이 기능을 선호합니다.

13. update_notebook

기존 노트북 이름 업데이트

Parameters:
- notebookId (string) - ID of the notebook to update
- title (string) - New notebook title

14. scan_unchecked_items

노트북 및 하위 노트북에서 완료되지 않은 할 일 항목(- [ ]) 스캔

Parameters:
- notebookId (string) - ID of the notebook to scan
- includeSubNotebooks (boolean, optional) - Whether to recursively scan sub-notebooks (default: true)

편집 의미론

update_note: 노트의 제목 및/또는 본문을 교체할 때 사용
append_to_note: 기존 콘텐츠를 유지하면서 노트 끝에 내용을 추가할 때 사용
move_note: 노트가 속한 노트북을 변경할 때 사용
update_notebook: 노트북 이름을 변경할 때 사용

사용 예시

AI 클라이언트에서의 대화 예시:

You: "Search for notes containing 'Python'"
AI: Using search_notes tool to search for relevant notes...

You: "Create a new notebook called 'Learning Plan'"
AI: Using create_notebook tool to create a new notebook...

You: "Create a note about JavaScript in the Learning Plan notebook"
AI: Using list_notebooks to find the notebook ID, then using create_note to create the note...

You: "Show the complete content of a specific note"
AI: Using get_note_content tool to retrieve note content...

You: "Update the title of note abc123 to Weekly Review"
AI: Using update_note tool to rename the note...

You: "Append these test results to note abc123"
AI: Using append_to_note tool to add the new content to the end of the note...

You: "Rename notebook xyz789 to Project Archive"
AI: Using update_notebook tool to rename the notebook...

You: "Scan my project notebook for all uncompleted todo items"
AI: Using scan_unchecked_items tool to scan all sub-notebooks...

문제 해결

연결 문제

Joplin 실행 확인
- Joplin 데스크톱 애플리케이션이 열려 있어야 합니다.
Web Clipper 설정 확인
- Web Clipper 서비스가 활성화되어 있는지 확인하세요.
- 포트 설정(기본값 41184)을 확인하세요.

오류 메시지 확인

# Use verbose mode to see errors
DEBUG=* npm start

일반적인 오류

"Joplin Web Clipper service not found": Joplin이 실행 중이고 Web Clipper가 활성화되어 있는지 확인하세요.
"Connection refused": 포트 설정이 올바른지 확인하세요.
"Unauthorized" 또는 "403 Forbidden": API 토큰이 필요합니다(아래 지침 참조).

🔑 API 토큰 필요

이 MCP 서버가 제대로 작동하려면 API 토큰이 필수입니다.

API 토큰 얻는 방법

Joplin에서 도구(Tools) → 옵션(Options) → Web Clipper로 이동
표시된 토큰 복사
시작 명령에 --token YOUR_TOKEN 추가

개발

# Run in development mode
npm run dev

# Compile
npm run build

# Prepare for publishing
npm run prepublishOnly

기술 아키텍처

언어: TypeScript/Node.js
MCP SDK: @modelcontextprotocol/sdk
HTTP 클라이언트: axios
CLI: commander
API: Joplin Web Clipper API

기술 세부 정보

노트북 검색: Joplin 검색 API의 폴더 검색 제한으로 인해, 클라이언트 측 필터링을 사용하여 노트북 검색 기능을 구현했습니다.
페이지네이션 처리: Joplin API의 페이지네이션 메커니즘(페이지당 기본 100개 항목)을 자동으로 처리하여, 노트북 및 노트 목록을 완전히 가져오고 하위 노트북 표시가 누락되는 문제를 해결했습니다.
오류 처리: Joplin API 오류 및 네트워크 연결 오류를 포함한 완전한 오류 처리 메커니즘을 갖추고 있습니다.
자동 감지: Joplin Web Clipper 포트(41184-41194) 자동 감지를 지원합니다.

라이선스

MIT 라이선스

기여

이슈 및 풀 리퀘스트는 언제나 환영합니다!

지원

문제가 발생하면 다음을 수행하세요:

Joplin Web Clipper가 정상적으로 실행 중인지 확인
오류 메시지 및 로그 검토
자세한 오류 정보를 포함하여 이슈 제출