클로드 MCP x Google 문서

최고의 Google Docs MCP 서버

Claude Desktop(또는 다른 MCP 클라이언트)을 Google Docs에 연결하세요!

🔥 이 강화된 서버로 달성할 수 있는 강력한 작업 10가지를 확인해 보세요!

이 향상된 서버는 모델 컨텍스트 프로토콜(MCP)과 fastmcp 라이브러리를 사용하여 Google 문서를 읽고, 쓰고, 서식을 지정하고, 구조화하는 데 필요한 포괄적인 도구를 제공합니다. 강력한 연결고리 역할을 하는 이 서버는 Claude와 같은 AI 비서가 고급 기능을 통해 프로그래밍 방식으로 문서와 상호 작용할 수 있도록 지원합니다.

특징:

문서 접근

문서 읽기: readGoogleDoc (일반 텍스트, JSON 구조 또는 마크다운)으로 콘텐츠 읽기
문서에 추가: appendToGoogleDoc 으로 문서에 텍스트 추가
텍스트 삽입: insertText 로 특정 위치에 텍스트 삽입
콘텐츠 삭제: deleteRange 사용하여 문서에서 콘텐츠 제거

서식 및 스타일

텍스트 서식: applyTextStyle 사용하여 다양한 스타일(굵게, 기울임꼴, 색상 등)을 적용합니다.
문단 서식: applyParagraphStyle (정렬, 간격 등)을 사용하여 문단 레이아웃을 제어합니다.
찾기 및 서식: formatMatchingText 사용하여 텍스트 콘텐츠별로 서식 지정(레거시 지원)

문서 구조

테이블: insertTable 로 테이블 만들기
페이지 나누기: insertPageBreak 로 페이지 나누기 삽입
실험적 기능: 자동 목록 감지를 위한 fixListFormatting 과 같은 도구

완성

Google 인증: 보안 OAuth 2.0 인증
MCP 호환: Claude 및 기타 MCP 클라이언트와 함께 사용하도록 설계되었습니다.

필수 조건

시작하기 전에 다음 사항이 있는지 확인하세요.

Node.js와 npm: 컴퓨터에 최신 버전의 Node.js(npm 포함)가 설치되어 있어야 합니다. nodejs.org 에서 다운로드할 수 있습니다(버전 18 이상 권장).
Git: 이 저장소를 복제하는 데 필요합니다. ( Git 다운로드 ).
Google 계정: 상호 작용하려는 Google 문서를 소유하거나 액세스할 수 있는 계정입니다.
명령줄 익숙함: 터미널이나 명령 프롬프트(macOS/Linux의 Terminal, Windows의 명령 프롬프트/PowerShell 등)를 사용하는 데 기본적인 익숙함이 필요합니다.
Claude Desktop(선택 사항): 이 서버를 Claude에 연결하려면 Claude Desktop 애플리케이션을 설치해야 합니다.

설치 지침

서버의 인스턴스를 실행하려면 다음 단계를 주의 깊게 따르세요.

1단계: Google Cloud 프로젝트 및 자격 증명(중요한 부분!)

이 서버는 사용자를 대신하여 Google API와 통신할 권한이 필요합니다. 사용자 서버에서만 사용할 수 있는 특수 "키"(사용자 인증 정보)를 생성하세요.

Google Cloud Console로 이동: 웹 브라우저를 열고 Google Cloud Console 로 이동합니다. Google 계정으로 로그인해야 할 수도 있습니다.
프로젝트 만들기 또는 선택:
- 프로젝트가 없으면 상단의 프로젝트 드롭다운 메뉴를 클릭하고 "새 프로젝트"를 선택하세요. 프로젝트 이름을 지정하고(예: "내 MCP 문서 서버") "만들기"를 클릭하세요.
- 기존 프로젝트가 있는 경우 하나를 선택하거나 새 프로젝트를 만들 수 있습니다.
API 활성화: 이 서버에서 사용하는 특정 Google 서비스를 켜야 합니다.
- 상단의 검색창에 "API 및 서비스"를 입력하고 "라이브러리"를 선택하세요.
- " Google Docs API "를 검색하여 클릭하세요. 그런 다음 " 사용 " 버튼을 클릭하세요.
- " Google 드라이브 API "를 검색하여 클릭하세요. 그런 다음 " 사용 " 버튼을 클릭하세요(파일이나 권한을 찾을 때 종종 필요합니다).
OAuth 동의 화면 구성: 이 화면은 사용자(보통 사용자 본인)에게 앱에서 어떤 권한을 원하는지 알려줍니다.
- 왼쪽 메뉴에서 "API 및 서비스" -> " OAuth 동의 화면 "을 클릭합니다.
- 사용자 유형 선택: " 외부 "를 선택하고 "만들기"를 클릭합니다.
- 앱 정보를 입력하세요:
  - 앱 이름: 사용자에게 표시되는 이름을 지정합니다(예: "Claude Docs MCP Access").
  - 사용자 지원 이메일: 이메일 주소를 선택하세요.
  - 개발자 연락처 정보: 이메일 주소를 입력하세요.
- " 저장하고 계속하기 "를 클릭하세요.
- 범위: " 범위 추가 또는 제거 "를 클릭하세요. 다음 범위를 검색하여 추가하세요.
  - https://www.googleapis.com/auth/documents (문서 읽기/쓰기 허용)
  - https://www.googleapis.com/auth/drive.file (앱에서 열거나 만든 특정 파일에 대한 액세스 허용)
  - " 업데이트 "를 클릭하세요.
- " 저장하고 계속하기 "를 클릭하세요.
- 테스트 사용자: " 사용자 추가 "를 클릭하세요. 로그인한 Google 이메일 주소를 입력하세요. " 추가 "를 클릭하세요. 이렇게 하면 "테스트" 모드에서도 앱을 사용할 수 있습니다 .
- " 저장 및 계속 "을 클릭하세요. 요약을 검토하고 " 대시보드로 돌아가기 "를 클릭하세요.
자격 증명(키!)을 만드세요:
- 왼쪽 메뉴에서 "API 및 서비스" -> " 자격 증명 "을 클릭합니다.
- 상단의 " + 자격 증명 만들기 "를 클릭하고 " OAuth 클라이언트 ID "를 선택합니다.
- 애플리케이션 유형: 드롭다운에서 " 데스크톱 앱 "을 선택하세요.
- 이름: 이름을 지정합니다(예: "MCP Docs 데스크톱 클라이언트").
- " 만들기 "를 클릭하세요.
⬇️ 자격 증명 파일 다운로드: 클라이언트 ID를 보여주는 상자가 나타납니다. " JSON 다운로드 " 버튼을 클릭하세요.
- 이 파일을 저장하세요. 파일 이름은 client_secret_....json 과 비슷할 것입니다.
- 중요: 다운로드한 파일의 이름을 credentials.json 으로 바꾸세요.
⚠️ 보안 경고: 이 credentials.json 파일을 비밀번호처럼 취급하세요! 공개적으로 공유하거나 GitHub에 커밋하지 마세요. 이 파일을 가진 사람은 누구든 귀하의 애플리케이션 인 척할 수 있습니다(단, 데이터 접근을 위해서는 사용자 동의가 필요합니다).

2단계: 서버 코드 가져오기

저장소 복제: 터미널/명령 프롬프트를 열고 다음을 실행합니다.지엑스피1
디렉토리로 이동:
cd mcp-googledocs-server
자격 증명 배치: 1.6단계에서 다운로드하여 이름을 바꾼 credentials.json 파일을 이 mcp-googledocs-server 폴더로 직접 이동하거나 복사합니다.

3단계: 종속성 설치

서버에는 package.json 파일에 지정된 일부 도우미 라이브러리가 필요합니다.

터미널에서( mcp-googledocs-server 디렉토리에 있는지 확인하세요) 다음을 실행합니다.
npm install
이렇게 하면 필요한 모든 패키지가 node_modules 폴더에 다운로드되어 설치됩니다.

4단계: 서버 코드 빌드

서버는 TypeScript( .ts )로 작성되었지만, Node.js에서 직접 실행할 수 있도록 JavaScript( .js )로 컴파일해야 합니다.

터미널에서 다음을 실행하세요.
npm run build
이는 TypeScript 컴파일러( tsc )를 사용하여 컴파일된 JavaScript 파일이 포함된 dist 폴더를 생성합니다.

5단계: 첫 번째 실행 및 Google 승인(한 번만)

이제 서버를 수동으로 한 번 실행하여 Google 계정 데이터 접근 권한을 부여해야 합니다. 이렇게 하면 권한 부여 내역을 저장하는 token.json 파일이 생성됩니다.

터미널에서 node 사용하여 컴파일된 서버를 실행합니다.
node ./dist/server.js
터미널을 시청하세요. 스크립트는 다음을 인쇄합니다.
- 상태 메시지(예: "인증을 시도하는 중...")
- "이 URL을 방문하여 이 앱을 승인하세요"라는 메시지 다음에 긴 https://accounts.google.com/... URL이 표시됩니다.
브라우저에서 권한 부여:
- 터미널에서 긴 URL 전체를 복사합니다.
- URL을 웹 브라우저에 붙여넣고 Enter를 누르세요.
- 1.4단계에서 테스트 사용자로 추가한 것과 동일한 Google 계정 으로 로그인합니다.
- Google에서 앱("Claude Docs MCP Access" 또는 유사 앱)의 Google Docs/Drive 접근 권한을 요청하는 화면을 표시합니다. 검토 후 " 허용 " 또는 " 허용 "을 클릭하세요.
승인 코드를 받으세요:
- 허용을 클릭하면 브라우저가 http://localhost 로 리디렉션을 시도하고 "이 사이트에 연결할 수 없습니다"라는 오류가 표시될 수 있습니다. 이는 정상적인 현상입니다!
- 브라우저 주소창의 URL을 자세히 살펴보세요. http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=... 처럼 보일 겁니다.
- code= 와 &scope 부분 사이의 긴 문자열을 복사하세요. 이것이 일회용 승인 코드입니다.
터미널에 코드 붙여넣기: 스크립트가 대기 중인 터미널로 돌아갑니다("해당 페이지의 코드를 여기에 입력하세요:"). 방금 복사한 코드를 붙여넣습니다.
Enter 키를 누르세요.
성공! 스크립트는 다음을 인쇄해야 합니다.
- "인증 성공!"
- "토큰은 .../token.json에 저장됨"
- 그런 다음 시작이 완료되고 "stdio를 통해 MCP 클라이언트 연결을 기다리는 중..." 또는 이와 유사한 메시지가 표시되고 종료됩니다(또는 Ctrl+C 눌러 중지할 수 있습니다).
✅ 확인: 이제 mcp-googledocs-server 폴더에 token.json 이라는 새 파일이 표시되어야 합니다.
⚠️ 보안 경고: 이 token.json 파일에는 서버가 다시 묻지 않고 Google 계정에 접근할 수 있도록 하는 키가 포함되어 있습니다. 비밀번호처럼 보호하세요. GitHub에 커밋하지 마세요. 포함된 .gitignore 파일을 사용하면 자동으로 이를 방지할 수 있습니다.

6단계: Claude Desktop 구성(선택 사항)

이 서버를 Claude Desktop과 함께 사용하려면 Claude에게 실행 방법을 알려줘야 합니다.

절대 경로를 찾으세요. 서버 코드의 전체 경로가 필요합니다.
- 터미널에서 mcp-googledocs-server 디렉토리에 있는지 확인하세요.
- pwd 명령(macOS/Linux) 또는 cd (Windows에서는 경로만 표시)을 실행합니다.
- 전체 경로를 복사합니다(예: /Users/yourname/projects/mcp-googledocs-server 또는 C:\Users\yourname\projects\mcp-googledocs-server ).
mcp_config.json 찾으세요: Claude의 구성 파일을 찾으세요:
- macOS: ~/Library/Application Support/Claude/mcp_config.json (Finder의 "이동" -> "폴더로 이동..." 메뉴를 사용하여 ~/Library/Application Support/Claude/ 붙여넣어야 할 수도 있습니다)
- Windows: %APPDATA%\Claude\mcp_config.json (파일 탐색기 주소창에 %APPDATA%\Claude 붙여넣습니다)
- 리눅스: ~/.config/Claude/mcp_config.json
- Claude 폴더나 mcp_config.json 파일이 없으면 만듭니다.
mcp_config.json 파일을 편집합니다. 텍스트 편집기에서 파일을 엽니다. mcpServers 섹션을 다음과 같이 추가하거나 수정합니다. /PATH/TO/YOUR/CLONED/REPO 6.1단계에서 복사한 실제 절대 경로로 바꿉니다 .
{ "mcpServers": { "google-docs-mcp": { "command": "node", "args": [ "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js" ], "env": {} } // Add commas here if you have other servers defined } // Other Claude settings might be here }
- "args" 의 경로가 올바르고 절대적인지 확인하세요!
- 파일이 이미 존재하는 경우, 이 항목을 기존 mcpServers 객체에 조심스럽게 병합하세요. JSON이 유효한지 확인하세요(쉼표 확인!).
mcp_config.json 저장합니다.
Claude Desktop을 다시 시작합니다. Claude를 완전히 닫았다가 다시 엽니다.

Claude Desktop과 함께 사용

구성이 완료되면 Claude와의 채팅에서 도구를 사용할 수 있습니다.

" google-docs-mcp 서버를 사용하여 ID가 YOUR_GOOGLE_DOC_ID 인 문서를 읽으세요."
"Google 문서 YOUR_GOOGLE_DOC_ID 의 내용을 얻을 수 있나요?"
google-docs-mcp 도구를 사용하여 '이것은 Claude가 추가했습니다!'를 문서 YOUR_GOOGLE_DOC_ID 에 추가합니다.

고급 사용 예:

텍스트 스타일 지정 : " applyTextStyle 사용하여 YOUR_GOOGLE_DOC_ID 문서에서 '중요 섹션' 텍스트를 굵고 빨간색(#FF0000)으로 지정합니다."
문단 스타일 지정 : " applyParagraphStyle 사용하여 YOUR_GOOGLE_DOC_ID 문서에서 '제목 여기'가 포함된 문단을 가운데 정렬합니다."
표 만들기 : " insertTable 도구를 사용하여 YOUR_GOOGLE_DOC_ID 문서의 인덱스 500에 3x4 표를 삽입합니다."
레거시 서식 : " formatMatchingText 사용하여 'Project Alpha'의 두 번째 인스턴스를 찾아 doc YOUR_GOOGLE_DOC_ID 에서 파란색(#0000FF)으로 만듭니다."

YOUR_GOOGLE_DOC_ID Google 문서 URL의 실제 ID( /d/ 와 /edit 사이의 긴 문자열)로 바꾸는 것을 잊지 마세요.

Claude는 필요한 경우 제공된 명령을 사용하여 자동으로 백그라운드에서 서버를 실행합니다. 더 이상 node ./dist/server.js 수동으로 실행할 필요가 없습니다 .

보안 및 토큰 저장

.gitignore : 이 저장소에는 .gitignore 파일이 포함되어 있어 중요한 credentials.json 및 token.json 파일을 실수로 커밋하는 것을 방지합니다. .gitignore 에서 이 줄을 삭제하지 마세요 .
토큰 저장소: 이 서버는 설정 과정의 편의성을 위해 Google 인증 토큰( token.json )을 프로젝트 폴더에 직접 저장합니다. 프로덕션 환경이나 보안에 더욱 민감한 환경에서는 시스템 키체인, 암호화된 파일 또는 전용 보안 관리 서비스 등을 사용하여 토큰을 더욱 안전하게 저장하는 것이 좋습니다.

문제 해결

Claude가 "실패" 또는 "첨부할 수 없음"을 표시합니다.
- mcp_config.json 에서 절대 경로를 다시 확인하세요.
- npm run build 성공적으로 실행했고 dist 폴더가 있는지 확인하세요.
- 터미널에서 mcp_config.json 파일의 node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js 명령을 수동으로 실행해 보세요. 출력된 오류를 살펴보세요.
- Claude Desktop 로그를 확인하세요(공식 MCP 디버깅 가이드 참조).
- 서버 코드의 모든 console.log 상태 메시지가 console.error 로 변경되었는지 확인하세요.
Google 인증 오류:
- 올바른 API(Docs, Drive)를 활성화했는지 확인하세요.
- OAuth 동의 화면에서 테스트 사용자로 이메일을 추가했는지 확인하세요.
- credentials.json 파일이 프로젝트 루트에 올바르게 배치되었는지 확인하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요. (참고: MIT 라이선스 텍스트가 포함된 LICENSE 파일을 저장소에 추가해야 합니다.)

Claude MCP x Google Docs

Integrations