Claude Code MCP 서버 연결로 노션 다루기

Claude Code 활용법

Claude Code는 코드 작업에 특화되어 있지만, MCP 서버를 연결하면 노션·GitHub·구글 시트 같은 외부 서비스까지 자연어로 다룰 수 있습니다. 이 글에서는 노션 MCP 서버를 예시로, 설정부터 실제 사용까지 전체 흐름을 정리합니다.

📌 3줄 요약

• MCP 서버는 Claude Code와 외부 서비스(노션 등) 사이의 통역사 역할을 하는 중간 다리다.
• 노션 API 토큰 발급 → .claude/settings.json에 MCP 서버 등록 → 재시작하면 바로 사용 가능하다.
• 여러 MCP 서버를 동시에 연결하면 서비스 간 연계 작업도 자연어 한 문장으로 처리할 수 있다.

📑 목차

• 1. MCP 서버가 뭔지 먼저 이해하기
• 2. Claude Code에 노션 MCP 서버 설정하기
• 3. 노션 MCP 연결 확인과 첫 명령 실행
• 4. MCP 서버 활용 팁과 주의할 점

MCP 서버가 뭔지 먼저 이해하기

Claude Code는 기본적으로 코드를 읽고 수정하는 데 특화되어 있습니다. 터미널에서 파일을 열고, 편집하고, 명령을 실행하는 작업은 Claude Code가 혼자서도 잘 해냅니다. 그런데 노션이나 데이터베이스처럼 외부 서비스를 다루려면, Claude Code 혼자서는 접근할 방법이 없습니다. 외부 서비스는 각각 고유한 API를 갖고 있고, Claude Code가 이 API를 직접 호출하는 기능은 내장되어 있지 않기 때문입니다.

이때 필요한 것이 MCP(Model Context Protocol) 서버입니다. MCP 서버는 Claude Code와 외부 서비스 사이에서 통역사 역할을 하는 중간 다리라고 생각하면 됩니다. Claude Code가 자연어로 요청을 보내면, MCP 서버가 그 요청을 해당 서비스의 API 형식에 맞게 변환해서 전달하는 구조입니다. 응답도 마찬가지로 MCP 서버가 받아서 Claude Code가 이해할 수 있는 형태로 돌려줍니다.

🔍 MCP 서버의 동작 원리

예를 들어 노션 MCP 서버를 연결하면, Claude Code가 "이 페이지 내용 읽어줘"라고 말했을 때 MCP 서버가 노션 API를 대신 호출합니다. Claude Code 입장에서는 마치 로컬 파일을 다루듯 노션 데이터를 자연스럽게 처리할 수 있게 되는 겁니다. 사용자 입장에서도 노션 API 문서를 읽거나 HTTP 요청을 직접 작성할 필요가 전혀 없습니다.

MCP 서버는 노션 외에도 GitHub, Slack, 구글 시트, PostgreSQL 같은 다양한 서비스용으로 이미 만들어져 있습니다. 커뮤니티에서 활발하게 새로운 MCP 서버를 개발하고 있어서, 지원하는 서비스 목록은 계속 늘어나고 있습니다. 한 번 연결 방법을 익히면 다른 서비스도 같은 방식으로 확장할 수 있으니, 이 글에서 노션을 예시로 전체 흐름을 잡아보겠습니다.

💬 개인 경험

제가 처음 MCP라는 단어를 봤을 때는 뭔가 복잡한 프로토콜(protocol)인 줄 알고 겁먹었습니다. 실제로 써보니 설정 파일 하나만 잘 작성하면 되는 구조라서, 개념보다 실습이 훨씬 쉬웠습니다. 프로토콜이라는 이름 때문에 네트워크 지식이 필요할 것 같지만, 사용자가 직접 프로토콜을 다룰 일은 없으니 안심하셔도 됩니다.

Claude Code에 노션 MCP 서버 설정하기

먼저 노션 쪽에서 API 토큰을 발급받아야 합니다. 노션 설정 → 내 연결 → 새 연결 만들기에서 내부 통합(Internal Integration)을 생성하면 토큰이 나옵니다. 통합을 만들 때 이름은 자유롭게 지으면 되고, 권한은 읽기와 쓰기 모두 체크하는 것을 권장합니다. 나중에 페이지 수정 기능까지 쓰려면 쓰기 권한이 필요하기 때문입니다.

⚠️ 주의

토큰을 복사한 뒤, Claude Code가 접근할 노션 페이지나 데이터베이스에서 "연결 추가"를 눌러 방금 만든 통합을 연결합니다. 이 단계를 빠뜨리면 토큰이 있어도 해당 페이지에 접근할 수 없으니 반드시 확인하십시오.

노션은 보안을 위해 페이지 단위로 접근 권한을 관리하기 때문에, 사용할 페이지마다 개별적으로 연결을 추가해야 합니다. 하위 페이지는 상위 페이지의 연결을 상속받으므로, 최상위 페이지에 한 번만 추가하면 하위 페이지들도 자동으로 접근 가능해집니다.

다음은 Claude Code 설정 파일에 MCP 서버를 등록하는 단계입니다. 프로젝트 루트의 .claude/settings.json 파일을 열고, mcpServers 항목에 아래와 같은 형식으로 추가합니다.

 

설정에서 핵심은 command, args, env 세 가지 필드입니다. command는 실행할 프로그램(여기서는 npx), args는 실행할 패키지 이름, env는 환경 변수를 의미합니다. 노션 API 토큰을 NOTION_API_TOKEN이라는 이름으로 env 안에 넣어야 합니다. 토큰 값은 ntn_으로 시작하는 긴 문자열인데, 앞뒤 공백 없이 정확히 붙여넣어야 합니다.

💡 팁

설정 파일을 저장한 뒤 Claude Code를 재시작하면 MCP 서버가 자동으로 로드됩니다. npx를 사용하기 때문에 별도 설치 과정 없이 처음 실행 시 자동으로 패키지를 내려받습니다. 다만 Node.js가 설치되어 있어야 npx가 동작하니, 아직 설치하지 않았다면 nodejs.org에서 LTS 버전을 먼저 설치하십시오.

 

💬 개인 경험

제가 직접 설정할 때 가장 많이 실수한 부분은 JSON 형식이었습니다. 쉼표 하나가 빠지거나 중괄호 짝이 안 맞으면 MCP 서버가 조용히 로드에 실패하니, 설정 후 반드시 Claude Code를 재시작해서 확인하는 습관을 들이는 것이 좋습니다. JSON 문법이 불안하다면 VS Code 같은 편집기에서 작성하면 실시간으로 오류를 잡아주어 편리합니다.

노션 MCP 연결 확인과 첫 명령 실행

Claude Code를 재시작한 뒤, MCP 서버가 정상적으로 연결됐는지 확인하는 방법이 있습니다. Claude Code에서 /mcp 명령을 입력하면 현재 연결된 MCP 서버 목록과 사용 가능한 도구(tool) 리스트가 표시됩니다. 이 목록에는 각 도구가 어떤 기능을 하는지 간단한 설명도 함께 나오므로, 어떤 작업이 가능한지 한눈에 파악할 수 있습니다.

 

목록에 notion 관련 도구들이 보이면 연결에 성공한 것입니다. 대표적으로 notion_search_pages, notion_read_page, notion_update_page 같은 도구들이 표시됩니다. 만약 서버가 목록에 나타나지 않는다면, 설정 파일의 JSON 문법 오류나 토큰 값이 비어 있는 경우가 대부분입니다. 설정 파일 경로가 .claude/settings.json이 맞는지도 다시 확인해 보십시오.

연결이 확인됐으면 간단한 명령부터 시도해 봅니다. "노션에서 최근 수정한 페이지 3개를 찾아줘"라고 입력하면, Claude Code가 MCP 서버를 통해 노션 API를 호출하고 결과를 보여줍니다. 복잡한 API 파라미터를 몰라도 자연어 한 문장으로 원하는 결과를 얻을 수 있다는 점이 MCP의 핵심 장점입니다. 결과는 페이지 제목, 마지막 수정 시간, 페이지 ID 등의 정보가 정리되어 출력됩니다.

더 실용적인 활용으로는 노션 데이터베이스 조회가 있습니다. "노션 데이터베이스에서 상태가 '진행중'인 항목만 뽑아줘"처럼 자연어로 요청하면, Claude Code가 필터 조건을 자동으로 구성해서 결과를 가져옵니다. 날짜 범위, 담당자, 우선순위 같은 복합 조건도 자연어로 설명하면 알아서 처리해줍니다.

 

🔍 MCP 도구 호출 승인이란?

처음 MCP 도구가 호출될 때 승인 프롬프트가 뜨는데, 이는 보안을 위한 정상적인 동작입니다. Claude Code는 외부 서비스에 접근하기 전에 사용자의 명시적 허가를 받도록 설계되어 있습니다. 매번 승인하기 번거롭다면 설정에서 해당 도구를 허용 목록에 추가할 수도 있습니다. .claude/settings.json의 allowedTools 항목에 도구 이름을 추가하면 이후 자동 승인됩니다.

💬 개인 경험

제가 써보니 노션 페이지 읽기는 거의 실패 없이 잘 동작했습니다. 다만 페이지 수정 명령은 노션 API 자체의 제약 때문에 일부 블록 타입에서 오류가 나는 경우가 있어서, 처음에는 읽기 위주로 활용하는 것을 권장합니다. 특히 토글 블록이나 임베드 블록은 수정이 안 되는 경우가 있으니 참고하십시오.

MCP 서버 활용 팁과 주의할 점

MCP 서버를 프로젝트별로 다르게 설정할 수 있다는 점이 큰 장점입니다. .claude/settings.json은 프로젝트 단위 설정이므로, A 프로젝트에서는 노션만, B 프로젝트에서는 노션과 PostgreSQL을 함께 연결하는 식으로 분리가 가능합니다. 이렇게 하면 프로젝트마다 필요한 도구만 로드되어 Claude Code의 응답 속도도 빨라지고, 불필요한 권한 노출도 방지할 수 있습니다.

여러 MCP 서버를 동시에 등록하는 것도 가능합니다. mcpServers 객체 안에 서버 이름을 키(key)로 여러 개 나열하면, Claude Code가 상황에 맞는 도구를 자동으로 선택해서 호출합니다. 예를 들어 "노션에서 할 일 목록 읽어서 GitHub 이슈로 만들어줘"라고 하면, 노션 MCP와 GitHub MCP를 순서대로 사용합니다. 서비스 간 연계 작업을 자연어 한 문장으로 처리할 수 있다는 것이 MCP의 진짜 힘입니다.

⚠️ 보안 필수 규칙

API 토큰을 설정 파일에 직접 쓰면 Git에 올라갈 위험이 있으니, 환경 변수나 .env 파일로 분리하고 .gitignore에 반드시 추가하십시오. 토큰이 유출되면 누구나 여러분의 노션 데이터에 접근할 수 있으므로, 이 부분은 꼭 신경 써야 합니다. 팀 프로젝트라면 .claude/settings.json 자체를 .gitignore에 넣는 것도 고려해 보십시오.

 

💡 연결 문제 해결 팁

MCP 서버가 응답하지 않거나 연결이 끊기는 경우도 간혹 발생합니다. 이때는 Claude Code를 재시작하는 것이 가장 빠른 해결 방법이고, 그래도 안 되면 npx 캐시를 삭제한 뒤 다시 시도해 보십시오. 네트워크 상태가 불안정할 때도 연결이 끊길 수 있으니, 인터넷 연결을 먼저 확인하는 것도 기본적인 점검 사항입니다.

노션 외에 시도해볼 만한 MCP 서버로는 GitHub MCP 서버가 있습니다. 이슈 조회, PR 생성 같은 작업을 Claude Code 안에서 바로 처리할 수 있어서, 개발 워크플로우를 한 곳에서 관리하기 편리합니다. 구글 시트 MCP 서버도 유용한데, 스프레드시트 데이터를 읽어서 분석하거나 자동으로 채우는 작업에 활용할 수 있습니다.

💬 개인 경험

제가 직접 노션과 GitHub MCP 서버를 동시에 연결해 써본 결과, 노션에 정리된 작업 목록을 읽고 GitHub 이슈로 자동 생성하는 흐름까지 만들 수 있었습니다. 처음 설정에 10분 정도 걸리지만 한 번 해두면 반복 작업이 크게 줄어드니, MCP 서버 연결은 Claude Code 활용의 첫 번째 확장 단계로 적극 추천합니다. 다음 글에서는 MCP 서버를 활용한 더 복잡한 자동화 시나리오를 다뤄볼 예정이니 기대해 주십시오.

✍️ 마치며

MCP 서버는 Claude Code의 능력을 외부 서비스까지 확장하는 핵심 기능입니다. 노션 API 토큰 발급 → 설정 파일 등록 → 재시작, 이 세 단계만 거치면 자연어로 노션 데이터를 자유롭게 다룰 수 있습니다. 복잡한 API 파라미터를 외울 필요 없이 원하는 작업을 말로 설명하면 되니, 비개발자도 충분히 활용할 수 있는 기능입니다. 오늘 소개한 노션을 시작으로, GitHub·구글 시트 등 다양한 MCP 서버를 하나씩 연결해 보시기 바랍니다.

#ClaudeCode #MCP서버 #노션연동 #AI자동화 #ModelContextProtocol #비개발자코딩