Google Docs MCP 서버

이 프로젝트는 Google Docs API와 함께 작동하는 MCP(Model Context Protocol) 서버를 제공합니다.

기능

이 MCP 서버는 다음 기능을 제공합니다.

Google Docs 문서 읽기
새로운 Google Docs 문서 만들기
기존 Google Docs 문서 업데이트
Google Docs 문서 검색

기술 스택

Node.js (v14 이상 권장)
TypeScript
@modelcontextprotocol/sdk - MCP SDK의 공식 구현
Google APIs Node.js Client - Google API 액세스

전제 조건

Node.js (v14 이상 권장)
npm 또는 yarn
Google Cloud Platform 프로젝트 및 액세스 자격 증명

설정

1. 프로젝트 복제 또는 다운로드

git clone [リポジトリURL]
cd docs-mcp

2. 종속성 설치

npm install

3. Google Cloud Platform 설정

Google Cloud Console 에서 프로젝트 만들기(또는 기존 프로젝트 선택)
Google Drive API 및 Google Docs API 사용
OAuth 2.0 클라이언트 ID를 만들고 자격 증명 다운로드
다운로드한 자격 증명 파일을 credentials.json 으로 프로젝트 루트에 배치

4. 환경 설정

.env 파일을 프로젝트 루트에 만들고 환경 변수를 설정합니다.

# アプリケーション環境
NODE_ENV=development

# ログ設定
# ログレベル: ERROR, WARN, INFO, DEBUG, TRACE
LOG_LEVEL=INFO
# 標準エラー出力にログを出力するかどうか（MCPの仕様に準拠）
LOG_USE_STDERR=true

# サーバー設定
SERVER_NAME=google-docs-mcp-server
SERVER_VERSION=1.0.0

# Google API認証情報
# 認証情報ファイルのパス（デフォルトは./credentials.json）
CREDENTIALS_PATH=./credentials.json
# トークンファイルのパス（デフォルトは./token.json）
TOKEN_PATH=./token.json

환경 변수 설명:

NODE_ENV : 애플리케이션 실행 환경(development, production, test)
LOG_LEVEL : 로그 세부 수준 (ERROR, WARN, INFO, DEBUG, TRACE)
LOG_USE_STDERR : 로그를 표준 에러 출력에 출력할지 어떨지 (MCP 사양에서는 표준 에러 출력을 사용)
SERVER_NAME : MCP 서버 이름
SERVER_VERSION : MCP 서버 버전
CREDENTIALS_PATH : Google API 자격 증명 파일 경로
TOKEN_PATH : 인증 토큰을 저장할 경로

개발 서버를 시작하고 토큰을 얻습니다.
npm run dev
실행 후 터미널에 권한 부여 URL이 표시됩니다. 해당 URL에 브라우저로 액세스하여 Google 계정으로 로그인하여 권한 부여를 완료한 후 표시되는 권한 부여 코드를 복사한 후 터미널에 붙여넣고 Enter 키를 token.json 십시오.

빌드 및 실행

빌드

npm run build

실행

일반 서버로 실행:

npm start

개발 모드에서 실행:

npm run dev

MCP 서버로 사용

이 프로젝트는 Model Context Protocol (MCP) 사양을 준수하는 서버입니다. MCP 클라이언트 (Cursor, Claude.ai 등)에서 직접 연결하여 사용할 수 있습니다.

MCP 클라이언트에서 설정

Cursor에서 설정

Cursor와 함께 사용하려면 .cursor/mcp.json 파일에 다음 설정을 추가합니다.

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/{プロジェクトへの絶対パス}/docs-mcp/dist/index.js"]
    }
  }
}

기타 MCP 클라이언트

다른 MCP 클라이언트는 표준 입출력 (stdio)을 사용하여 통신합니다. 클라이언트 설정에 따라 적절한 명령을 지정하십시오.

제공되는 MCP 도구

read_google_document

Google Docs 문서의 내용을 읽습니다.

매개변수 :

documentId (string): 읽을 Google Docs 문서의 ID

사용 예 :

// MCPクライアントでの使用例
const response = await client.callTool({
  name: "read_google_document",
  arguments: {
    documentId: "your-document-id"
  }
});

create_google_document

새 Google Docs 문서를 만듭니다.

매개변수 :

title (string): 새 문서 제목
content (string, 옵션): 문서의 초기 내용

사용 예 :

const response = await client.callTool({
  name: "create_google_document",
  arguments: {
    title: "ドキュメントタイトル",
    content: "初期コンテンツ"
  }
});

update_google_document

기존 Google Docs 문서를 업데이트합니다.

매개변수 :

documentId (string): 업데이트할 Google 문서 문서의 ID
content (string): 추가 또는 업데이트할 콘텐츠
startPosition (number, 옵션): 업데이트를 시작할 위치
endPosition (number, 옵션): 업데이트를 종료할 위치

사용 예 :

const response = await client.callTool({
  name: "update_google_document",
  arguments: {
    documentId: "your-document-id",
    content: "追加または更新するコンテンツ",
    startPosition: 1,
    endPosition: 10
  }
});

search_google_documents

Google Docs 문서를 검색합니다.

매개변수 :

query (string): 검색 쿼리
maxResults (number, 옵션): 검색할 최대 결과 수(기본값: 10)

사용 예 :

const response = await client.callTool({
  name: "search_google_documents",
  arguments: {
    query: "検索キーワード",
    maxResults: 5
  }
});

프로그램의 사용 예

TypeScript 및 JavaScript 프로그램에서 MCP 클라이언트를 통해 사용하는 예:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // MCPクライアントの作成
  const client = new Client({
    name: "google-docs-client",
    version: "1.0.0"
  });

  // Google Docs MCPサーバーへの接続
  const transport = new StdioClientTransport({
    command: "npm",
    args: ["run", "mcp"]
  });

  await client.connect(transport);

  // サーバー情報の取得
  const info = await client.getServerInfo();
  console.log("利用可能なツール:", info.tools);

  // ドキュメントの検索
  const searchResult = await client.callTool({
    name: "search_google_documents",
    arguments: {
      query: "会議資料",
      maxResults: 5
    }
  });
  console.log("検索結果:", searchResult);

  // 接続を閉じる
  await client.disconnect();
}

main().catch(console.error);

문제 해결

커서에서 연결 오류가 발생하는 경우

커서를 완전히 다시 시작합니다.
.cursor/mcp.json 설정이 올바른지 확인하십시오.
수동으로 MCP 서버를 시작하여 동작 확인:
npm run dev
이 명령을 실행할 때 'Google Docs MCP 서버가 시작되었습니다.'라는 메시지가 표시되고 프로세스가 종료되지 않고 계속 작동하는지 확인합니다.
커서 설정에서 'MCP 서버' 섹션을 확인하고 'google-docs' 서버가 표시되는지 확인합니다.

Google 인증 오류가 발생하는 경우

credentials.json 파일이 프로젝트 루트에 올바르게 배치되었는지 확인합니다.
token.json 파일이 존재하는 경우 삭제하고 다시 인증을 시도하십시오.
Google Cloud Console에서 해당 프로젝트에 대해 Google Drive API와 Google Docs API가 사용 설정되어 있는지 확인합니다.

확장 및 구성

이 MCP 서버는 확장성을 고려하여 설계되었으며 다음과 같이 새로운 기능을 추가할 수 있습니다.

src/googleDocsService.ts - GoogleDocsService 클래스에 새 메서드 추가
src/index.ts - 새로운 도구를 정의하고 서버에 등록

주의사항

처음 실행하면 Google 인증을 위한 승인 화면이 표시됩니다. 인증 후 토큰이 파일에 저장되고 이후 실행 시 자동으로 사용됩니다.
API 사용량에 따라 Google Cloud Platform 요금이 부과될 수 있습니다.

라이센스

MIT License

Google Docs MCP Server

Integrations