Google Docs MCP Server

Google Docs APIと連携するMCP（Model Context Protocol）サーバーです。AI システムがGoogle Docsを直接操作できるインターフェースを提供します。

機能

このMCPサーバーが提供するツール：

read_google_document - Google Docsドキュメントの読み取り
create_google_document - 新しいGoogle Docsドキュメントの作成
update_google_document - 既存のGoogle Docsドキュメントの更新
search_google_documents - Google Docsドキュメントの検索

アーキテクチャの特徴

依存性注入コンテナ - ServiceContainerによるサービス管理
階層化エラーハンドリング - 統一されたエラー処理システム
自動ツール登録 - 設定ベースのツール管理
完全なTypeScript - 型安全性と開発効率の向上

技術スタック

Runtime: Node.js (v14以上)
Language: TypeScript (ES2020/ESM)
MCP SDK: @modelcontextprotocol/sdk v1.10.2
Google APIs: googleapis v148.0.0
Configuration: dotenv + zod validation

セットアップ

1. プロジェクトの準備

git clone <repository-url>
cd docs-mcp
npm install

2. Google Cloud Platform の設定

Google Cloud Console でプロジェクトを作成
以下のAPIを有効化：
- Google Docs API
- Google Drive API
OAuth 2.0 クライアントIDを作成し、認証情報をダウンロード
credentials.json としてプロジェクトルートに配置

3. 環境設定（オプション）

.env ファイルで設定をカスタマイズできます：

# アプリケーション環境 (development, production, test)
NODE_ENV=development

# ログ設定 (ERROR, WARN, INFO, DEBUG, TRACE)
LOG_LEVEL=INFO
LOG_USE_STDERR=true

# サーバー情報
SERVER_NAME=google-docs-mcp-server
SERVER_VERSION=1.0.0

# 認証ファイルパス（カスタマイズ可能）
CREDENTIALS_PATH=./credentials.json
TOKEN_PATH=./token.json

4. 初回認証

npm run dev

ターミナルに表示される認証URLにアクセスし、Googleアカウントで認証してください。認証後に取得したコードをターミナルに入力すると token.json が生成されます。

開発コマンド

# 開発サーバー（hot reload）
npm run dev

# プロダクションビルド
npm run build

# ビルド後の実行
npm start

# MCP デバッグモード
npm run mcp

# コード品質チェック
npm run lint

ビルドプロセス: TypeScript コンパイル → 実行権限設定 → 認証ファイル複製

MCP クライアント設定

Cursor での設定

.cursor/mcp.json に追加：

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/absolute/path/to/docs-mcp/dist/index.js"]
    }
  }
}

Claude Desktop での設定

claude_desktop_config.json に追加：

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/absolute/path/to/docs-mcp/dist/index.js"]
    }
  }
}

注意: ビルド後の dist/index.js を指定してください。

提供ツール

read_google_document

Google Docs ドキュメントの内容を読み取ります。

パラメータ:

documentId (string): 読み取るドキュメントのID

create_google_document

新しい Google Docs ドキュメントを作成します。

パラメータ:

title (string): ドキュメントタイトル
content (string, オプション): 初期内容

update_google_document

既存の Google Docs ドキュメントを更新します。

パラメータ:

documentId (string): 更新するドキュメントのID
content (string): 追加または更新するコンテンツ
startPosition (number, オプション): 更新開始位置
endPosition (number, オプション): 更新終了位置

search_google_documents

Google Docs ドキュメントを検索します。

パラメータ:

query (string): 検索クエリ
maxResults (number, オプション): 最大結果数（デフォルト: 10）

プログラムでの利用例

MCP SDK を使用した TypeScript/JavaScript での利用：

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

async function main() {
  const client = new Client({
    name: "google-docs-client",
    version: "1.0.0"
  });

  const transport = new StdioClientTransport({
    command: "node",
    args: ["/absolute/path/to/docs-mcp/dist/index.js"]
  });

  await client.connect(transport);

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

  // 新規ドキュメント作成
  const createResult = await client.callTool({
    name: "create_google_document",
    arguments: {
      title: "新しいドキュメント",
      content: "初期コンテンツ"
    }
  });

  await client.disconnect();
}

main().catch(console.error);

アーキテクチャ詳細

コアコンポーネント

ServiceContainer (src/core/container.ts) - 依存性注入とサービスライフサイクル管理
GoogleDocsMcpServer (src/mcp/server.ts) - MCP サーバーの管理と初期化
ToolRegistry (src/mcp/registry.ts) - ツールの自動登録システム
BaseMcpTool (src/mcp/tools/base.ts) - 全ツールの共通基底クラス

サービス層

AuthService (src/services/authService.ts) - Google OAuth2 認証管理
GoogleDocsService (src/services/googleDocsService.ts) - Google Docs/Drive API操作

設定システム

統一設定管理 (src/config/index.ts) - 環境変数とデフォルト値の統合
型安全な設定 - Zod による設定値の検証
階層化ログシステム (src/utils/logger.ts) - モジュール別ログ出力

トラブルシューティング

MCP クライアント接続エラー

ビルドの確認: npm run build が成功しているか
パス設定: 設定ファイルで dist/index.js への絶対パスを指定
権限設定: chmod 755 dist/index.js で実行権限を確認
手動テスト: npm run mcp でサーバーが起動するか確認

Google 認証エラー

認証ファイル: credentials.json がプロジェクトルートに存在するか
API有効化: Google Cloud Console で必要なAPIが有効か
トークン再作成: token.json を削除して再認証
スコープ確認: Docs API と Drive API の権限が設定されているか

開発時のデバッグ

# 詳細ログでデバッグ実行
LOG_LEVEL=DEBUG npm run dev

# MCP通信のデバッグ
npm run mcp

拡張ガイド

新しいツールの追加

src/mcp/tools/ に新しいツールクラスを作成
BaseMcpTool を継承して実装
ToolRegistry.registerDefaultTools() に追加

サービスの拡張

src/core/interfaces.ts でインターフェースを定義
src/services/ に実装クラスを作成
ServiceContainer に追加

注意事項

初回実行時の Google 認証が必要
Google Cloud Platform の API 使用料金が発生する可能性
MCP クライアントでは絶対パスでの指定が必要

ライセンス

MIT License

Google Docs MCP Server

Google Docs APIと連携するMCP（Model Context Protocol）サーバーです。AI システムがGoogle Docsを直接操作できるインターフェースを提供します。

機能

このMCPサーバーが提供するツール：

read_google_document - Google Docsドキュメントの読み取り
create_google_document - 新しいGoogle Docsドキュメントの作成
update_google_document - 既存のGoogle Docsドキュメントの更新
search_google_documents - Google Docsドキュメントの検索

アーキテクチャの特徴

依存性注入コンテナ - ServiceContainerによるサービス管理
階層化エラーハンドリング - 統一されたエラー処理システム
自動ツール登録 - 設定ベースのツール管理
完全なTypeScript - 型安全性と開発効率の向上

技術スタック

Runtime: Node.js (v14以上)
Language: TypeScript (ES2020/ESM)
MCP SDK: @modelcontextprotocol/sdk v1.10.2
Google APIs: googleapis v148.0.0
Configuration: dotenv + zod validation

セットアップ

1. プロジェクトの準備

git clone <repository-url>
cd docs-mcp
npm install

2. Google Cloud Platform の設定

Google Cloud Console でプロジェクトを作成
以下のAPIを有効化：
- Google Docs API
- Google Drive API
OAuth 2.0 クライアントIDを作成し、認証情報をダウンロード
credentials.json としてプロジェクトルートに配置

3. 環境設定（オプション）

.env ファイルで設定をカスタマイズできます：

# アプリケーション環境 (development, production, test)
NODE_ENV=development

# ログ設定 (ERROR, WARN, INFO, DEBUG, TRACE)
LOG_LEVEL=INFO
LOG_USE_STDERR=true

# サーバー情報
SERVER_NAME=google-docs-mcp-server
SERVER_VERSION=1.0.0

# 認証ファイルパス（カスタマイズ可能）
CREDENTIALS_PATH=./credentials.json
TOKEN_PATH=./token.json

4. 初回認証

npm run dev

開発コマンド

# 開発サーバー（hot reload）
npm run dev

# プロダクションビルド
npm run build

# ビルド後の実行
npm start

# MCP デバッグモード
npm run mcp

# コード品質チェック
npm run lint

ビルドプロセス: TypeScript コンパイル → 実行権限設定 → 認証ファイル複製

MCP クライアント設定

Cursor での設定

.cursor/mcp.json に追加：

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/absolute/path/to/docs-mcp/dist/index.js"]
    }
  }
}

Claude Desktop での設定

claude_desktop_config.json に追加：

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/absolute/path/to/docs-mcp/dist/index.js"]
    }
  }
}

注意: ビルド後の dist/index.js を指定してください。

提供ツール

read_google_document

Google Docs ドキュメントの内容を読み取ります。

パラメータ:

documentId (string): 読み取るドキュメントのID

create_google_document

新しい Google Docs ドキュメントを作成します。

パラメータ:

title (string): ドキュメントタイトル
content (string, オプション): 初期内容

update_google_document

既存の Google Docs ドキュメントを更新します。

パラメータ:

documentId (string): 更新するドキュメントのID
content (string): 追加または更新するコンテンツ
startPosition (number, オプション): 更新開始位置
endPosition (number, オプション): 更新終了位置

search_google_documents

Google Docs ドキュメントを検索します。

パラメータ:

query (string): 検索クエリ
maxResults (number, オプション): 最大結果数（デフォルト: 10）

プログラムでの利用例

MCP SDK を使用した TypeScript/JavaScript での利用：

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

async function main() {
  const client = new Client({
    name: "google-docs-client",
    version: "1.0.0"
  });

  const transport = new StdioClientTransport({
    command: "node",
    args: ["/absolute/path/to/docs-mcp/dist/index.js"]
  });

  await client.connect(transport);

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

  // 新規ドキュメント作成
  const createResult = await client.callTool({
    name: "create_google_document",
    arguments: {
      title: "新しいドキュメント",
      content: "初期コンテンツ"
    }
  });

  await client.disconnect();
}

main().catch(console.error);

アーキテクチャ詳細

コアコンポーネント

ServiceContainer (src/core/container.ts) - 依存性注入とサービスライフサイクル管理
GoogleDocsMcpServer (src/mcp/server.ts) - MCP サーバーの管理と初期化
ToolRegistry (src/mcp/registry.ts) - ツールの自動登録システム
BaseMcpTool (src/mcp/tools/base.ts) - 全ツールの共通基底クラス

サービス層

AuthService (src/services/authService.ts) - Google OAuth2 認証管理
GoogleDocsService (src/services/googleDocsService.ts) - Google Docs/Drive API操作

設定システム

統一設定管理 (src/config/index.ts) - 環境変数とデフォルト値の統合
型安全な設定 - Zod による設定値の検証
階層化ログシステム (src/utils/logger.ts) - モジュール別ログ出力

トラブルシューティング

MCP クライアント接続エラー

ビルドの確認: npm run build が成功しているか
パス設定: 設定ファイルで dist/index.js への絶対パスを指定
権限設定: chmod 755 dist/index.js で実行権限を確認
手動テスト: npm run mcp でサーバーが起動するか確認

Google 認証エラー

認証ファイル: credentials.json がプロジェクトルートに存在するか
API有効化: Google Cloud Console で必要なAPIが有効か
トークン再作成: token.json を削除して再認証
スコープ確認: Docs API と Drive API の権限が設定されているか

開発時のデバッグ

# 詳細ログでデバッグ実行
LOG_LEVEL=DEBUG npm run dev

# MCP通信のデバッグ
npm run mcp

拡張ガイド

新しいツールの追加

src/mcp/tools/ に新しいツールクラスを作成
BaseMcpTool を継承して実装
ToolRegistry.registerDefaultTools() に追加

サービスの拡張

src/core/interfaces.ts でインターフェースを定義
src/services/ に実装クラスを作成
ServiceContainer に追加

注意事項

初回実行時の Google 認証が必要
Google Cloud Platform の API 使用料金が発生する可能性
MCP クライアントでは絶対パスでの指定が必要

ライセンス

MIT License