Outline Wiki 자체 구축 가이드 (2): Claude MCP 연동

이번 글에서 해결할 문제

지난 글에서 Outline Wiki를 자체 구축했으므로, 이제 그 위력을 발휘할 차례입니다. 바로 MCP (Model Context Protocol)를 사용하여 Claude, Codex가 우리의 문서를 추가, 편집, 정리할 수 있도록 만드는 것입니다.

이번 글은 주로 Outline + Claude에 대해 다루며, 다음 글은 Outline + Codex에 대해 다룰 예정입니다.

본 가이드를 따라 설정을 완료하면, Claude Desktop은 MCP를 통해 Outline 도구를 호출할 수 있습니다. 예시는 다음과 같습니다:

• Outline 문서 검색 또는 목록 나열
• 문서 컬렉션(Collection) 내의 문서 읽기 및 편집
• 문서 컬렉션 생성
• 문서 이동
• MCP Server가 제공하는 기타 Outline 작업 실행

사전 준비

시작하기 전에 다음 환경이 갖춰져 있는지 확인하십시오:

1. Claude Desktop 설치
2. Node.js 설치
3. 정상적으로 연결 가능한 Outline

Outline API Token 생성

설정 진입

Outline에 로그인한 후, 왼쪽 하단 계정 옆의 「⋯」를 클릭하고 「Settings (설정)」를 선택합니다.

왼쪽 하단 메뉴에서 설정으로 진입

API & Access 활성화

왼쪽 설정 메뉴에서 「API & Access」를 선택한 다음, 오른쪽 상단의 「New API Key (새 API 키)」를 클릭합니다.

API & Access에 진입하여 새 API 키 생성

키 이름, 범위 및 만료일 설정

용도를 쉽게 식별할 수 있는 이름(예: "AI MCP", "Claude MCP" 등)을 입력하는 것을 권장합니다.

기본 프로세스의 설정은 다음과 같습니다:

• 범위 (Scope): 비워둠
• 만료일 (Expiration Date): 기한 없음

API 키 범위 및 만료일 설정

범위를 비워두는 것은 일반적으로 특정 API 권한을 제한하지 않음을 의미합니다. 이 설정은 조작이 가장 간단하지만 권한도 큽니다.

API Token 복사

생성이 완료되면 「Copy (복사)」를 클릭하고, Token은 한 번만 표시되므로 안전한 곳에 임시 저장해 두십시오.

Outline API Token 복사

주의: API Token은 계정 인증 정보와 동일하므로 Git, 공개 문서, 블로그 게시물, 채팅 그룹 또는 암호화되지 않은 노트에 붙여넣지 마십시오.

Claude Desktop MCP 설정

Claude Desktop 설정 파일 열기

Claude Desktop은 Windows와 macOS에서 동일한 설정 파일 이름을 사용하지만, 저장 경로는 다릅니다.

Windows

아무 폴더나 열고 파일 경로창에 다음을 붙여넣으세요:

%APPDATA%\Claude\claude_desktop_config.json

또는 Win + R을 누른 뒤 동일한 경로를 붙여넣고 Enter를 눌러도 됩니다.

macOS: Finder를 사용하여 열기

1. Finder를 엽니다.
2. 상단 메뉴에서 「이동」을 클릭합니다.
3. 「폴더로 이동...」을 선택합니다.
4. 다음 경로를 붙여넣습니다:

~/Library/Application Support/Claude/

5. 다음 파일을 찾아 엽니다:

claude_desktop_config.json

macOS: 터미널을 사용하여 열기

터미널에서 다음 명령어를 실행할 수도 있습니다:

mkdir -p "$HOME/Library/Application Support/Claude"
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

이 세 가지 명령어는 순서대로 설정 폴더를 생성하고, 설정 파일을 만든 후, macOS 텍스트 편집기로 파일을 엽니다.

파일이 이미 존재하는 경우, 수정을 진행하기 전에 복사본을 만들어 백업해 두는 것을 권장합니다.

Outline MCP Server 추가

다음 설정을 JSON의 최상위 객체 내 mcpServers에 추가하세요:

{
  "mcpServers": {
    "outline": {
...

NODE_TLS_REJECT_UNAUTHORIZED=0은 Node.js의 TLS 인증서 검증을 비활성화합니다. 이는 신뢰할 수 있는 내부 네트워크에서 임시로 테스트할 때만 적합하며, 공개 네트워크나 운영 환경에서는 권장되지 않습니다. 더 안전한 방법은 MCP Server에 시스템이 신뢰할 수 있는 유효한 인증서를 설정하는 것입니다.

Windows와 macOS는 원칙적으로 이 설정을 공유할 수 있습니다. 만약 macOS에서 npx를 직접 찾을 수 없다면, 먼저 터미널에서 다음을 실행하세요:

which npx

만약 결과가 다음과 같이 반환된다면:

/opt/homebrew/bin/npx

command를 전체 경로로 변경할 수 있습니다:

"command": "/opt/homebrew/bin/npx"

일반적인 위치는 다음과 같습니다:

주의: 표에 있는 경로를 그대로 복사하지 마세요. 반드시 which npx를 먼저 실행한 후, 본인의 컴퓨터에서 실제로 반환된 결과를 사용해야 합니다.

다음 내용을 교체해 주세요:

예를 들어 MCP Server가 내부 네트워크에 있는 경우, 다음과 같이 변경할 수 있습니다:

"https://192.168.x.x:3023/mcp"

기존 설정을 병합할 때 주의사항

claude_desktop_config.json에 이미 다른 설정이 있는 경우, 파일 전체를 덮어쓰지 마세요. mcpServers 항목만 최상위 객체에 병합해야 합니다.

Windows 설정 예시

기존에 다른 필드가 이미 있는 경우의 예시입니다:

{
  "coworkUserFilesPath": "C:\\Users\\Sean\\Claude",
  "preferences": {},
...

macOS 설정 예시

macOS도 동일한 JSON 구조를 사용합니다. npx를 직접 실행할 수 있는 경우:

{
  "preferences": {},
  "mcpServers": {
...

만약 Claude Desktop에서 npx를 찾을 수 없다면, which npx 명령어로 확인한 전체 경로를 command에 입력하세요. 예시:

"command": "/opt/homebrew/bin/npx"

JSON 작성 시 흔히 발생하는 오류는 다음과 같습니다:

• 필드 사이에 쉼표(comma)가 누락된 경우
• 마지막 필드 뒤에 불필요한 쉼표가 붙은 경우
• 중괄호({}) 또는 대괄호([])의 짝이 맞지 않는 경우
• Windows 경로에서 백슬래시(\)를 \\로 작성하지 않은 경우
• macOS 경로에 공백이 포함되어 있는데 터미널 명령에서 따옴표나 이스케이프 문자(escape character)를 사용하지 않은 경우
• mcpServers를 최상위 객체(outermost object) 외부로 붙여넣은 경우

Claude Desktop 재시작

설정 파일을 수정한 후에는 반드시 Claude Desktop을 완전히 종료했다가 다시 실행해야 합니다.

단순히 창을 닫는 것만으로는 프로그램이 완전히 종료되지 않을 수 있습니다:

• Windows: 시스템 트레이에서 Claude를 종료하거나, 작업 관리자(Task Manager)에서 Claude가 여전히 백그라운드에서 실행 중인지 확인하세요.
• macOS: Command + Q를 누르거나, 상단 메뉴 바에서 「Claude」 → 「Quit Claude」를 선택하세요. 필요한 경우 「활성 상태 보기(Activity Monitor)」에서 프로그램이 실행 중인지 확인할 수 있습니다.

재시작 시 Claude Desktop은 다음 과정을 수행합니다:

1. claude_desktop_config.json 파일을 읽습니다.
2. npx를 통해 mcp-remote를 실행합니다.
3. Authorization Header를 사용하여 Outline MCP Server에 연결합니다.
4. MCP Server가 제공하는 도구(tools)를 로드합니다.

처음 npx -y mcp-remote를 실행할 때는 패키지 다운로드가 필요할 수 있으므로, 이후 실행 시보다 대기 시간이 다소 길어질 수 있습니다.

Outline MCP 연결 성공 테스트

Claude Desktop을 다시 연 후, 다음과 같이 입력해 보세요:

Outline MCP에 연결되었나요? 현재 사용할 수 있는 Outline 도구 목록을 보여주세요.

그 다음, 실제 읽기 기능을 테스트합니다:

Outline에서 현재 볼 수 있는 문서와 문서 집합(Collection)을 나열해 주세요.

특정 작업을 지정할 수도 있습니다:

Outline에서 "프론트엔드"라는 키워드가 포함된 문서를 검색해 주세요.

연결에 성공하면 Claude는 Outline 도구가 로드되었음을 표시하며, 워크스페이스 내의 문서 또는 Collection 정보를 반환할 수 있습니다.