MCP Server 연동

다양한 AI 도구에서 NLook을 직접 연동하여 문서와 할일을 관리할 수 있습니다.

개요

MCP(Model Context Protocol)는 AI 도구가 외부 서비스와 상호작용할 수 있게 해주는 프로토콜입니다. NLook MCP Server를 사용하면:

• AI 도구에서 직접 문서 작성/저장

• AI 생성 콘텐츠를 NLook에 자동 저장

• 할일 목록 관리

• 기존 문서 조회 및 수정

지원 AI 클라이언트

클라이언트	지원 상태	설명
Claude Desktop	✅ 지원	Anthropic 공식 데스크탑 앱
Claude Code	✅ 지원	터미널 기반 AI 코딩 어시스턴트
Cursor	✅ 지원	AI 기반 코드 에디터
Windsurf	✅ 지원	Codeium의 AI IDE
VS Code + Copilot	✅ 지원	GitHub Copilot MCP 확장
Zed	✅ 지원	차세대 코드 에디터
Cline	✅ 지원	VS Code용 AI 코딩 어시스턴트

설치 방법

1. API Key 발급

먼저 NLook에서 API Key를 발급받아야 합니다.

1. NLook 설정 페이지로 이동합니다

2. API Key 관리 섹션을 찾습니다

3. 새 API Key 생성 버튼을 클릭합니다

4. 이름과 권한을 설정합니다:

   • 이름: Claude MCP Server (또는 원하는 이름)

   • 권한: 필요한 권한 선택

     • 읽기: 문서/할일 조회

     • 쓰기: 문서/할일 생성/수정

     • 삭제: 문서/할일 삭제

5. 생성 버튼을 클릭합니다

6. 표시된 API Key를 복사하여 안전한 곳에 보관합니다

⚠️ 중요: API Key는 생성 시 한 번만 표시됩니다. 분실 시 새로 발급받아야 합니다.

2. MCP Server 설치

npm을 통한 설치

npm install -g nlook-mcp

Claude Desktop 설정

Claude Desktop의 설정 파일에 NLook MCP Server를 추가합니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nlook": {
      "command": "npx",
      "args": ["-y", "nlook-mcp"],
      "env": {
        "NLOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code 설정

Claude Code CLI를 사용하여 NLook MCP Server를 추가합니다.

claude mcp add nlook -e NLOOK_API_KEY=your-api-key-here -- npx -y nlook-mcp

설정 확인:

claude mcp list

정상적으로 추가되었다면 다음과 같이 표시됩니다:

Checking MCP server health...

nlook: npx -y nlook-mcp - ✓ Connected

💡 참고: Claude Code는 프로젝트별 .mcp.json 파일도 지원합니다. 프로젝트 루트에 .mcp.json 파일을 생성하면 해당 프로젝트에서만 MCP 서버를 사용할 수 있습니다.

Cursor 설정

Cursor의 MCP 설정 파일에 NLook을 추가합니다.

macOS: ~/.cursor/mcp.json Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "nlook": {
      "command": "npx",
      "args": ["-y", "nlook-mcp"],
      "env": {
        "NLOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

설정 후 Cursor를 재시작합니다.

Windsurf 설정

Windsurf(Codeium)의 MCP 설정 파일에 NLook을 추가합니다.

macOS: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "nlook": {
      "command": "npx",
      "args": ["-y", "nlook-mcp"],
      "env": {
        "NLOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

설정 후 Windsurf를 재시작합니다.

VS Code + GitHub Copilot 설정

VS Code에서 GitHub Copilot과 함께 MCP를 사용하려면:

1. VS Code 설정(settings.json)에 MCP 서버를 추가합니다:

{
  "github.copilot.chat.experimental.mcpServers": {
    "nlook": {
      "command": "npx",
      "args": ["-y", "nlook-mcp"],
      "env": {
        "NLOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

1. VS Code를 재시작합니다.

💡 참고: GitHub Copilot의 MCP 지원은 실험적 기능입니다.

Zed 설정

Zed 에디터의 설정 파일에 MCP 서버를 추가합니다.

설정 파일: ~/.config/zed/settings.json

{
  "context_servers": {
    "nlook": {
      "command": {
        "path": "npx",
        "args": ["-y", "nlook-mcp"],
        "env": {
          "NLOOK_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Cline (VS Code 확장) 설정

Cline 확장 프로그램에서 MCP 서버를 설정합니다:

1. VS Code에서 Cline 확장 프로그램을 설치합니다

2. Cline 설정 패널을 열고 MCP Servers 탭으로 이동합니다

3. "Add Server" 버튼을 클릭하고 다음 정보를 입력합니다:

   • Name: nlook

   • Command: npx

   • Args: -y nlook-mcp

4. 환경 변수를 추가합니다:

   • NLOOK_API_KEY: your-api-key-here

또는 Cline의 MCP 설정 파일을 직접 편집합니다:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "nlook": {
      "command": "npx",
      "args": ["-y", "nlook-mcp"],
      "env": {
        "NLOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

환경 변수 설정 (선택사항)

기본 API URL을 변경하고 싶은 경우 NLOOK_API_URL 환경 변수를 설정할 수 있습니다:

{
  "mcpServers": {
    "nlook": {
      "command": "npx",
      "args": ["-y", "nlook-mcp"],
      "env": {
        "NLOOK_API_KEY": "your-api-key-here",
        "NLOOK_API_URL": "https://nlook.me"
      }
    }
  }
}

💡 참고: NLOOK_API_URL의 기본값은 https://nlook.me입니다.

3. Claude Desktop 재시작

설정 파일을 저장한 후 Claude Desktop을 재시작합니다.

---

사용 가능한 도구 (Tools)

NLook MCP Server는 다음과 같은 도구를 제공합니다:

문서 도구

도구 이름	설명	필수 파라미터	선택 파라미터
create_document	새 문서 저장	title, content	tags, is_public
list_documents	문서 목록 조회	-	limit, search, tags
get_document	특정 문서 조회	id	-
update_document	문서 수정	id	title, content, tags
delete_document	문서 삭제	id	-

할일 도구

도구 이름	설명	필수 파라미터	선택 파라미터
create_task	새 할일 생성	title	notes, priority, due_date, task_list_id
list_tasks	할일 목록 조회	-	limit, status, priority, task_list_id
update_task	할일 수정	id	title, notes, priority, status, due_date
delete_task	할일 삭제	id	-
complete_task	할일 완료 처리	id	-

할일 목록 도구

도구 이름	설명	필수 파라미터	선택 파라미터
list_task_lists	할일 목록 그룹 조회	-	-
create_task_list	할일 목록 생성	name	color

---

사용 방법 (자연어 명령 예시)

Claude Desktop에서 자연어로 명령하면 적절한 도구가 자동으로 호출됩니다.

문서 저장

이 내용을 NLook에 저장해줘:

# 오늘의 회의록

- 참석자: 김철수, 이영희
- 주제: 프로젝트 진행 상황 논의
- 결론: 다음 주까지 프로토타입 완성

## 액션 아이템
1. 디자인 검토 (김철수)
2. API 개발 (이영희)

결과: create_document 도구가 호출되어 문서가 저장됩니다.

태그와 함께 문서 저장

다음 내용을 NLook에 저장해줘. 태그는 "개발", "React", "학습"으로 해줘:

# React Hooks 정리

useState, useEffect, useMemo...

문서 조회

NLook에서 최근 문서 5개를 보여줘

NLook에서 "회의록"이 포함된 문서를 찾아줘

NLook 문서 ID 123번의 내용을 보여줘

문서 수정

NLook 문서 123번의 제목을 "주간 회의록 - 12월 1주차"로 변경해줘

NLook 문서 123번에 다음 내용을 추가해줘: [추가할 내용]

할일 관리

할일 생성

NLook에 할일 추가해줘:
- 제목: 보고서 작성
- 우선순위: 높음
- 마감일: 2024-12-31

NLook에 "디자인 리뷰" 할일을 추가해줘. 우선순위는 중간으로.

할일 조회

NLook에서 오늘 할일 목록을 보여줘

NLook에서 완료되지 않은 높은 우선순위 할일만 보여줘

NLook에서 진행 중인 할일을 보여줘

할일 완료

NLook 할일 456번을 완료 처리해줘

NLook에서 "보고서 작성" 할일을 완료로 바꿔줘

할일 수정

NLook 할일 456번의 마감일을 다음 주 금요일로 변경해줘

NLook 할일 456번의 우선순위를 높음으로 변경해줘

할일 목록(그룹) 관리

NLook에 있는 모든 할일 목록을 보여줘

NLook에 "프로젝트 A" 이름의 새 할일 목록을 만들어줘

---

파라미터 상세 설명

우선순위 (priority)

값	설명	아이콘
none	없음	-
low	낮음	🟢
medium	보통	🟡
high	높음	🔴

상태 (status)

값	설명	아이콘
pending	대기 중	⬜
in_progress	진행 중	🔄
completed	완료	✅

날짜 형식 (due_date)

ISO 8601 형식을 사용합니다:

• 2024-12-31T23:59:59Z

• 2024-12-31

자연어로 "내일", "다음 주 금요일" 등으로 말하면 Claude가 자동으로 변환합니다.

API 엔드포인트

MCP Server는 내부적으로 다음 API를 사용합니다. 기본 URL은 https://nlook.me입니다.

문서 (Documents)

Method	Endpoint	설명
POST	/api/v1/public/documents	새 문서 생성
GET	/api/v1/public/documents	문서 목록 조회
GET	/api/v1/public/documents/{id}	특정 문서 조회
PUT	/api/v1/public/documents/{id}	문서 수정
DELETE	/api/v1/public/documents/{id}	문서 삭제

할일 (Tasks)

Method	Endpoint	설명
POST	/api/v1/public/tasks	새 할일 생성
GET	/api/v1/public/tasks	할일 목록 조회
GET	/api/v1/public/tasks/{id}	특정 할일 조회
PUT	/api/v1/public/tasks/{id}	할일 수정
DELETE	/api/v1/public/tasks/{id}	할일 삭제

할일 목록 (Task Lists)

Method	Endpoint	설명
GET	/api/v1/public/task-lists	할일 목록 그룹 조회
POST	/api/v1/public/task-lists	새 할일 목록 생성

인증

모든 API 요청에는 API Key 인증이 필요합니다. 두 가지 방식을 지원합니다:

방식 1: X-API-Key 헤더 (권장)

X-API-Key: your-api-key-here

방식 2: Authorization Bearer 헤더

Authorization: Bearer your-api-key-here

💡 권장: X-API-Key 헤더 방식을 사용하세요. 더 명시적이고 다른 인증 시스템과 충돌하지 않습니다.

요청 예시

문서 생성

curl -X POST https://nlook.me/api/v1/public/documents \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "새 문서",
    "content": "<p>문서 내용입니다.</p>",
    "tags": ["태그1", "태그2"]
  }'

문서 목록 조회

curl -X GET "https://nlook.me/api/v1/public/documents?limit=10&search=회의록" \
  -H "X-API-Key: your-api-key-here"

할일 생성

curl -X POST https://nlook.me/api/v1/public/tasks \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "새 할일",
    "notes": "할일 메모",
    "priority": "high",
    "due_date": "2024-12-31T23:59:59Z"
  }'

할일 완료 처리

curl -X PUT https://nlook.me/api/v1/public/tasks/123 \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

할일 목록 조회 (필터링)

curl -X GET "https://nlook.me/api/v1/public/tasks?status=pending&priority=high&limit=20" \
  -H "X-API-Key: your-api-key-here"

권한 설명

권한	설명	사용 예
read	문서/할일 조회	기존 데이터 읽기
write	문서/할일 생성/수정	새 문서 저장, 기존 문서 수정
delete	문서/할일 삭제	문서/할일 삭제

💡 권장: 일반적인 사용에는 read와 write 권한만 부여하는 것이 좋습니다.

요청 제한

기본적으로 시간당 1,000회의 API 호출이 가능합니다. API Key 생성 시 이 제한을 조정할 수 있습니다.

문제 해결

API Key가 유효하지 않은 경우

{
  "success": false,
  "error": "Invalid API key"
}

해결 방법:

1. API Key가 올바르게 복사되었는지 확인

2. API Key가 활성 상태인지 설정 페이지에서 확인

3. 만료되지 않았는지 확인

권한 오류

{
  "success": false,
  "error": "API key does not have write permission"
}

해결 방법:

1. 설정 페이지에서 API Key의 권한 확인

2. 필요한 권한이 부여되어 있는지 확인

3. 필요시 새 API Key 발급

요청 제한 초과

{
  "success": false,
  "error": "Rate limit exceeded"
}

해결 방법:

1. 잠시 후 다시 시도

2. API Key의 요청 제한 설정 확인

지원

문제가 발생하면 다음 채널을 통해 도움을 받으세요:

• NLook 웹사이트

• 이메일: [email protected]