google-workspace-api-mcp 1.0.0

package/README.md

@@ -0,0 +1,309 @@
+# Google Workspace API MCP
+
+Google Workspace API를 사용해 Google Drive 파일 검색, Google Docs 문서 조회 및 편집, Google Sheets 스프레드시트 조회 및 수정을 제공하는 MCP 서버입니다.
+
+## 주요 기능
+
+- `google_drive_search_files`: Google Drive에서 파일 이름 또는 본문 검색으로 문서, 스프레드시트, 기타 파일을 찾습니다.
+- `google_drive_get_file`: Drive 파일 ID로 파일 메타데이터, 웹 링크, 소유자, 권한 정보를 조회합니다.
+- `google_docs_get_document`: Google Docs 문서 구조와 추출된 일반 텍스트를 조회합니다.
+- `google_docs_create_document`: 새 Google Docs 문서를 만들고 선택적으로 초기 텍스트를 삽입합니다.
+- `google_docs_append_text`: 기존 Google Docs 문서 끝에 텍스트를 추가합니다.
+- `google_docs_insert_text`: 지정한 Google Docs 구조 인덱스에 텍스트를 삽입합니다.
+- `google_docs_replace_text`: 문서 안의 특정 텍스트를 전체 치환합니다.
+- `google_sheets_create_spreadsheet`: 새 Google Sheets 스프레드시트를 만들고 선택적으로 시트 이름을 지정합니다.
+- `google_sheets_get_values`: A1 표기법 범위의 셀 값을 읽습니다.
+- `google_sheets_update_values`: 지정한 범위의 셀 값을 덮어씁니다.
+- `google_sheets_append_values`: 지정한 범위에 행 데이터를 추가합니다.
+
+## 사전 준비
+
+1. Google Cloud Console에서 프로젝트를 생성합니다.
+2. 다음 API를 사용 설정합니다.
+   - Google Drive API
+   - Google Docs API
+   - Google Sheets API
+3. 서비스 계정을 만들고 JSON 키를 발급합니다.
+4. 접근하려는 문서, 스프레드시트, 폴더를 서비스 계정 이메일에 공유합니다.
+5. MCP 실행 환경에 인증 정보를 설정합니다.
+
+서비스 계정은 명시적으로 공유받은 파일과 폴더에만 접근할 수 있습니다.
+
+## 인증 설정
+
+이 서버는 세 가지 인증 방식을 지원합니다.
+
+### 1. MCP 설정에 직접 입력
+
+JSON 키 파일을 따로 두기 싫다면 서비스 계정 JSON에서 `client_email`, `private_key`, `project_id` 값을 꺼내 MCP 설정의 환경 변수로 넣을 수 있습니다.
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "google-workspace-api-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_EMAIL": "your-service-account@your-project.iam.gserviceaccount.com",
+        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
+        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id"
+      }
+    }
+  }
+}
+```
+
+`GOOGLE_PRIVATE_KEY`의 줄바꿈은 위 예시처럼 `\\n`으로 입력하면 됩니다. 서버가 실행 시 실제 개행 문자로 변환합니다.
+
+### 2. 서비스 계정 JSON 전체 입력
+
+서비스 계정 JSON 전체를 환경 변수에 직접 넣을 수도 있습니다. MCP 설정 JSON 안에 다시 JSON 문자열을 넣어야 하므로 따옴표 이스케이프가 번거롭습니다. 가능하면 base64 인코딩 값을 권장합니다.
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "google-workspace-api-mcp"],
+      "env": {
+        "GOOGLE_SERVICE_ACCOUNT_JSON": "base64_encoded_service_account_json"
+      }
+    }
+  }
+}
+```
+
+PowerShell에서 base64 값을 만드는 예시:
+
+```powershell
+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Content .\service-account.json -Raw)))
+```
+
+### 3. 키 파일 경로 사용
+
+로컬 파일 경로를 사용하는 방식도 계속 지원합니다.
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "google-workspace-api-mcp"],
+      "env": {
+        "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account.json"
+      }
+    }
+  }
+}
+```
+
+`GOOGLE_APPLICATION_CREDENTIALS`도 동일하게 사용할 수 있습니다.
+
+필요한 OAuth scope:
+
+- `https://www.googleapis.com/auth/documents`
+- `https://www.googleapis.com/auth/drive`
+- `https://www.googleapis.com/auth/spreadsheets`
+
+서비스 계정 JSON, private key, 키 파일은 README, 소스 코드, 공개 저장소에 커밋하지 마세요. MCP 클라이언트의 secret/env 관리 기능이나 로컬 환경 변수를 사용하세요.
+
+## 설치해서 사용하기
+
+MCP 클라이언트 설정 예시:
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "google-workspace-api-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_EMAIL": "your-service-account@your-project.iam.gserviceaccount.com",
+        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
+        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id"
+      }
+    }
+  }
+}
+```
+
+## 로컬 개발
+
+저장소를 받은 뒤 패키지 디렉터리에서 실행합니다.
+
+```bash
+cd google-workspace-api-mcp
+npm install
+npm run build
+npm start
+```
+
+로컬 빌드 결과물을 직접 실행하는 MCP 설정 예시:
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "node",
+      "args": ["./build/index.js"],
+      "cwd": "/path/to/google-workspace-api-mcp",
+      "env": {
+        "GOOGLE_CLIENT_EMAIL": "your-service-account@your-project.iam.gserviceaccount.com",
+        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
+        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id"
+      }
+    }
+  }
+}
+```
+
+`cwd`는 사용자의 실제 프로젝트 디렉터리로 바꾸면 됩니다. Windows라면 예를 들어 `C:\\path\\to\\google-workspace-api-mcp`처럼 적습니다.
+
+## Docker
+
+이미지 빌드:
+
+```bash
+docker build -t google-workspace-api-mcp .
+```
+
+Docker 기반 MCP 설정 예시:
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GOOGLE_CLIENT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com",
+        "-e",
+        "GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
+        "-e",
+        "GOOGLE_PROJECT_ID=your-google-cloud-project-id",
+        "google-workspace-api-mcp"
+      ]
+    }
+  }
+}
+```
+
+## JSON 호출 예시
+
+### Drive 파일 검색
+
+```json
+{
+  "query": "회의록",
+  "mime_type": "application/vnd.google-apps.document",
+  "page_size": 10
+}
+```
+
+### Google Docs 문서 생성
+
+```json
+{
+  "title": "주간 업무 보고",
+  "text": "이번 주 진행 상황\n- MCP 서버 구성\n- Google Docs 연동 테스트\n"
+}
+```
+
+### Google Docs 텍스트 추가
+
+```json
+{
+  "document_id": "google_docs_document_id",
+  "text": "\n다음 주 계획\n- 배포 검증\n- 사용자 문서 보강\n"
+}
+```
+
+### Google Sheets 값 읽기
+
+```json
+{
+  "spreadsheet_id": "google_sheets_spreadsheet_id",
+  "range": "Sheet1!A1:D20"
+}
+```
+
+### Google Sheets 행 추가
+
+```json
+{
+  "spreadsheet_id": "google_sheets_spreadsheet_id",
+  "range": "Sheet1!A:D",
+  "values": [
+    ["날짜", "항목", "상태", "메모"],
+    ["2026-06-27", "MCP 배포 준비", "완료", "npx 실행 구성"]
+  ],
+  "value_input_option": "USER_ENTERED"
+}
+```
+
+## LLM 채팅 프롬프트 예시
+
+MCP가 연결된 LLM 채팅에서 아래처럼 자연어로 요청할 수 있습니다.
+
+```text
+내 Google Drive에서 "분기 보고서"가 들어간 Google Docs 문서를 찾아서 최근 수정일 기준으로 정리해줘.
+```
+
+```text
+이 문서 ID의 내용을 읽고 핵심 결정 사항과 할 일을 요약해줘.
+```
+
+```text
+새 Google Docs 문서를 만들고 제목은 "프로젝트 킥오프 메모"로 해줘. 본문에는 참석자, 목표, 다음 액션 섹션을 넣어줘.
+```
+
+```text
+이 스프레드시트의 Sheet1!A1:F50 범위를 읽고 상태가 지연인 항목만 표로 정리해줘.
+```
+
+```text
+이 스프레드시트 Sheet1에 오늘 날짜, 작업명, 상태, 메모를 한 행으로 추가해줘.
+```
+
+## 배포
+
+```bash
+npm run build
+npm pack --dry-run
+npm login
+npm publish
+```
+
+scope 패키지로 이름을 바꾸는 경우:
+
+```bash
+npm publish --access public
+```
+
+배포 후 MCP 클라이언트에서는 다음처럼 실행할 수 있습니다.
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "google-workspace-api-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_EMAIL": "your-service-account@your-project.iam.gserviceaccount.com",
+        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nYOUR_PRIVATE_KEY_CONTENT\\n-----END PRIVATE KEY-----\\n",
+        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id"
+      }
+    }
+  }
+}
+```
+
+## 주의 사항
+
+- Google Workspace API 사용량과 조직 정책에 따라 할당량 제한이나 접근 제한이 발생할 수 있습니다.
+- 서비스 계정은 명시적으로 공유받은 파일과 폴더에만 접근할 수 있습니다.
+- 문서 편집 도구는 Google Docs API의 구조 인덱스를 사용합니다. 일반적인 문서 시작 위치는 `1`입니다.
+- 민감한 문서와 스프레드시트를 다룰 때는 MCP 클라이언트 로그, 터미널 기록, 환경 변수 노출 범위를 확인하세요.

package/build/index.js

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { google } from "googleapis";
+import { z } from "zod";
+const SERVER_NAME = "google-workspace-api-mcp";
+const SERVER_VERSION = "1.0.0";
+const scopes = [
+    "https://www.googleapis.com/auth/documents",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/spreadsheets",
+];
+const optionalString = z.string().min(1).optional();
+const valueMatrixSchema = z.array(z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])));
+const searchFilesSchema = z.object({
+    query: optionalString,
+    mime_type: optionalString,
+    page_size: z.number().int().min(1).max(100).default(10),
+    include_trashed: z.boolean().default(false),
+});
+const fileIdSchema = z.object({
+    file_id: z.string().min(1),
+});
+const createDocumentSchema = z.object({
+    title: z.string().min(1),
+    text: z.string().optional(),
+});
+const appendDocumentTextSchema = z.object({
+    document_id: z.string().min(1),
+    text: z.string(),
+});
+const insertDocumentTextSchema = z.object({
+    document_id: z.string().min(1),
+    index: z.number().int().min(1),
+    text: z.string(),
+});
+const replaceDocumentTextSchema = z.object({
+    document_id: z.string().min(1),
+    search_text: z.string().min(1),
+    replace_text: z.string(),
+    match_case: z.boolean().default(false),
+});
+const createSpreadsheetSchema = z.object({
+    title: z.string().min(1),
+    sheets: z.array(z.string().min(1)).default([]),
+});
+const sheetRangeSchema = z.object({
+    spreadsheet_id: z.string().min(1),
+    range: z.string().min(1),
+});
+const updateValuesSchema = sheetRangeSchema.extend({
+    values: valueMatrixSchema,
+    value_input_option: z.enum(["RAW", "USER_ENTERED"]).default("USER_ENTERED"),
+});
+const appendValuesSchema = updateValuesSchema.extend({
+    insert_data_option: z.enum(["INSERT_ROWS", "OVERWRITE"]).default("INSERT_ROWS"),
+});
+class GoogleWorkspaceApiMcpServer {
+    server;
+    docs;
+    drive;
+    sheets;
+    constructor() {
+        this.server = new Server({
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        const auth = this.createAuthClient();
+        this.docs = google.docs({ version: "v1", auth });
+        this.drive = google.drive({ version: "v3", auth });
+        this.sheets = google.sheets({ version: "v4", auth });
+        this.registerToolListHandler();
+        this.registerToolCallHandler();
+    }
+    createAuthClient() {
+        const serviceAccountJson = process.env.GOOGLE_SERVICE_ACCOUNT_JSON;
+        const keyFile = process.env.GOOGLE_SERVICE_ACCOUNT_KEY_FILE || process.env.GOOGLE_APPLICATION_CREDENTIALS;
+        const inlineCredentials = this.getInlineServiceAccountCredentials();
+        if (serviceAccountJson) {
+            return new google.auth.GoogleAuth({
+                credentials: this.parseServiceAccountJson(serviceAccountJson),
+                scopes,
+            });
+        }
+        if (inlineCredentials) {
+            return new google.auth.GoogleAuth({
+                credentials: inlineCredentials,
+                scopes,
+            });
+        }
+        return new google.auth.GoogleAuth({
+            keyFile,
+            scopes,
+        });
+    }
+    getInlineServiceAccountCredentials() {
+        const clientEmail = process.env.GOOGLE_CLIENT_EMAIL;
+        const privateKey = process.env.GOOGLE_PRIVATE_KEY;
+        if (!clientEmail && !privateKey) {
+            return undefined;
+        }
+        if (!clientEmail || !privateKey) {
+            throw new McpError(ErrorCode.InvalidRequest, "GOOGLE_CLIENT_EMAIL and GOOGLE_PRIVATE_KEY must be set together.");
+        }
+        return {
+            type: "service_account",
+            project_id: process.env.GOOGLE_PROJECT_ID,
+            private_key_id: process.env.GOOGLE_PRIVATE_KEY_ID,
+            client_email: clientEmail,
+            private_key: privateKey.replace(/\\n/g, "\n"),
+        };
+    }
+    parseServiceAccountJson(raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            try {
+                return JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+            }
+            catch {
+                throw new McpError(ErrorCode.InvalidRequest, "GOOGLE_SERVICE_ACCOUNT_JSON must be a JSON object string or base64-encoded JSON.");
+            }
+        }
+    }
+    registerToolListHandler() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: "google_drive_search_files",
+                    description: "Search Google Drive files visible to the configured Google account.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            query: { type: "string", description: "Drive search text matched against file name or full text." },
+                            mime_type: { type: "string", description: "Optional exact MIME type filter." },
+                            page_size: { type: "number", description: "Maximum results, 1-100. Default: 10." },
+                            include_trashed: { type: "boolean", description: "Whether to include trashed files. Default: false." },
+                        },
+                    },
+                },
+                {
+                    name: "google_drive_get_file",
+                    description: "Get Google Drive file metadata by file id.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            file_id: { type: "string", description: "Google Drive file id." },
+                        },
+                        required: ["file_id"],
+                    },
+                },
+                {
+                    name: "google_docs_get_document",
+                    description: "Read a Google Docs document structure and extracted plain text.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            file_id: { type: "string", description: "Google Docs document id." },
+                        },
+                        required: ["file_id"],
+                    },
+                },
+                {
+                    name: "google_docs_create_document",
+                    description: "Create a new Google Docs document, optionally with initial plain text.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string", description: "Document title." },
+                            text: { type: "string", description: "Optional initial plain text." },
+                        },
+                        required: ["title"],
+                    },
+                },
+                {
+                    name: "google_docs_append_text",
+                    description: "Append plain text to the end of a Google Docs document.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            document_id: { type: "string", description: "Google Docs document id." },
+                            text: { type: "string", description: "Plain text to append." },
+                        },
+                        required: ["document_id", "text"],
+                    },
+                },
+                {
+                    name: "google_docs_insert_text",
+                    description: "Insert plain text at a specific Google Docs structural index.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            document_id: { type: "string", description: "Google Docs document id." },
+                            index: { type: "number", description: "Google Docs insertion index. Use 1 for the start of the body." },
+                            text: { type: "string", description: "Plain text to insert." },
+                        },
+                        required: ["document_id", "index", "text"],
+                    },
+                },
+                {
+                    name: "google_docs_replace_text",
+                    description: "Replace all matching text in a Google Docs document.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            document_id: { type: "string", description: "Google Docs document id." },
+                            search_text: { type: "string", description: "Text to find." },
+                            replace_text: { type: "string", description: "Replacement text." },
+                            match_case: { type: "boolean", description: "Whether matching is case-sensitive. Default: false." },
+                        },
+                        required: ["document_id", "search_text", "replace_text"],
+                    },
+                },
+                {
+                    name: "google_sheets_create_spreadsheet",
+                    description: "Create a Google Sheets spreadsheet, optionally with named sheets.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string", description: "Spreadsheet title." },
+                            sheets: { type: "array", items: { type: "string" }, description: "Optional sheet names." },
+                        },
+                        required: ["title"],
+                    },
+                },
+                {
+                    name: "google_sheets_get_values",
+                    description: "Read cell values from a Google Sheets range.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            spreadsheet_id: { type: "string", description: "Spreadsheet id." },
+                            range: { type: "string", description: "A1 notation range, for example Sheet1!A1:D20." },
+                        },
+                        required: ["spreadsheet_id", "range"],
+                    },
+                },
+                {
+                    name: "google_sheets_update_values",
+                    description: "Overwrite values in a Google Sheets range.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            spreadsheet_id: { type: "string", description: "Spreadsheet id." },
+                            range: { type: "string", description: "A1 notation range." },
+                            values: { type: "array", items: { type: "array", items: {} }, description: "Two-dimensional value array." },
+                            value_input_option: { type: "string", enum: ["RAW", "USER_ENTERED"], description: "Default: USER_ENTERED." },
+                        },
+                        required: ["spreadsheet_id", "range", "values"],
+                    },
+                },
+                {
+                    name: "google_sheets_append_values",
+                    description: "Append rows to a Google Sheets range.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            spreadsheet_id: { type: "string", description: "Spreadsheet id." },
+                            range: { type: "string", description: "A1 notation range." },
+                            values: { type: "array", items: { type: "array", items: {} }, description: "Two-dimensional value array." },
+                            value_input_option: { type: "string", enum: ["RAW", "USER_ENTERED"], description: "Default: USER_ENTERED." },
+                            insert_data_option: { type: "string", enum: ["INSERT_ROWS", "OVERWRITE"], description: "Default: INSERT_ROWS." },
+                        },
+                        required: ["spreadsheet_id", "range", "values"],
+                    },
+                },
+            ],
+        }));
+    }
+    registerToolCallHandler() {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                switch (name) {
+                    case "google_drive_search_files":
+                        return this.textResponse(await this.searchFiles(searchFilesSchema.parse(args)));
+                    case "google_drive_get_file":
+                        return this.textResponse(await this.getFile(fileIdSchema.parse(args).file_id));
+                    case "google_docs_get_document":
+                        return this.textResponse(await this.getDocument(fileIdSchema.parse(args).file_id));
+                    case "google_docs_create_document":
+                        return this.textResponse(await this.createDocument(createDocumentSchema.parse(args)));
+                    case "google_docs_append_text":
+                        return this.textResponse(await this.appendDocumentText(appendDocumentTextSchema.parse(args)));
+                    case "google_docs_insert_text":
+                        return this.textResponse(await this.insertDocumentText(insertDocumentTextSchema.parse(args)));
+                    case "google_docs_replace_text":
+                        return this.textResponse(await this.replaceDocumentText(replaceDocumentTextSchema.parse(args)));
+                    case "google_sheets_create_spreadsheet":
+                        return this.textResponse(await this.createSpreadsheet(createSpreadsheetSchema.parse(args)));
+                    case "google_sheets_get_values":
+                        return this.textResponse(await this.getSheetValues(sheetRangeSchema.parse(args)));
+                    case "google_sheets_update_values":
+                        return this.textResponse(await this.updateSheetValues(updateValuesSchema.parse(args)));
+                    case "google_sheets_append_values":
+                        return this.textResponse(await this.appendSheetValues(appendValuesSchema.parse(args)));
+                    default:
+                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof McpError) {
+                    throw error;
+                }
+                if (error instanceof z.ZodError) {
+                    throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.issues.map((issue) => issue.message).join(", ")}`);
+                }
+                throw new McpError(ErrorCode.InternalError, this.getErrorMessage(error));
+            }
+        });
+    }
+    async searchFiles(input) {
+        const filters = input.include_trashed ? [] : ["trashed = false"];
+        if (input.query) {
+            const escaped = input.query.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+            filters.push(`(name contains '${escaped}' or fullText contains '${escaped}')`);
+        }
+        if (input.mime_type) {
+            const escapedMimeType = input.mime_type.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+            filters.push(`mimeType = '${escapedMimeType}'`);
+        }
+        const response = await this.drive.files.list({
+            q: filters.length > 0 ? filters.join(" and ") : undefined,
+            pageSize: input.page_size,
+            fields: "files(id,name,mimeType,webViewLink,createdTime,modifiedTime,owners(displayName,emailAddress))",
+            orderBy: "modifiedTime desc",
+            supportsAllDrives: true,
+            includeItemsFromAllDrives: true,
+        });
+        return response.data.files ?? [];
+    }
+    async getFile(fileId) {
+        const response = await this.drive.files.get({
+            fileId,
+            fields: "id,name,mimeType,webViewLink,createdTime,modifiedTime,size,owners(displayName,emailAddress),permissions(id,type,role,emailAddress,displayName)",
+            supportsAllDrives: true,
+        });
+        return response.data;
+    }
+    async getDocument(documentId) {
+        const response = await this.docs.documents.get({ documentId });
+        return {
+            documentId: response.data.documentId,
+            title: response.data.title,
+            revisionId: response.data.revisionId,
+            text: this.extractDocumentText(response.data.body?.content ?? []),
+            document: response.data,
+        };
+    }
+    async createDocument(input) {
+        const response = await this.docs.documents.create({
+            requestBody: {
+                title: input.title,
+            },
+        });
+        const documentId = response.data.documentId;
+        if (documentId && input.text) {
+            await this.insertDocumentText({
+                document_id: documentId,
+                index: 1,
+                text: input.text,
+            });
+        }
+        return {
+            documentId,
+            title: response.data.title,
+            webViewLink: documentId ? `https://docs.google.com/document/d/${documentId}/edit` : undefined,
+        };
+    }
+    async appendDocumentText(input) {
+        const document = await this.docs.documents.get({ documentId: input.document_id });
+        const endIndex = document.data.body?.content?.at(-1)?.endIndex;
+        if (!endIndex || endIndex < 2) {
+            throw new McpError(ErrorCode.InternalError, "Could not determine document end index.");
+        }
+        return this.insertDocumentText({
+            document_id: input.document_id,
+            index: endIndex - 1,
+            text: input.text,
+        });
+    }
+    async insertDocumentText(input) {
+        const response = await this.docs.documents.batchUpdate({
+            documentId: input.document_id,
+            requestBody: {
+                requests: [
+                    {
+                        insertText: {
+                            location: { index: input.index },
+                            text: input.text,
+                        },
+                    },
+                ],
+            },
+        });
+        return {
+            documentId: input.document_id,
+            replies: response.data.replies ?? [],
+        };
+    }
+    async replaceDocumentText(input) {
+        const response = await this.docs.documents.batchUpdate({
+            documentId: input.document_id,
+            requestBody: {
+                requests: [
+                    {
+                        replaceAllText: {
+                            containsText: {
+                                text: input.search_text,
+                                matchCase: input.match_case,
+                            },
+                            replaceText: input.replace_text,
+                        },
+                    },
+                ],
+            },
+        });
+        return {
+            documentId: input.document_id,
+            replies: response.data.replies ?? [],
+        };
+    }
+    async createSpreadsheet(input) {
+        const response = await this.sheets.spreadsheets.create({
+            requestBody: {
+                properties: {
+                    title: input.title,
+                },
+                sheets: input.sheets.map((title) => ({
+                    properties: { title },
+                })),
+            },
+        });
+        return {
+            spreadsheetId: response.data.spreadsheetId,
+            spreadsheetUrl: response.data.spreadsheetUrl,
+            properties: response.data.properties,
+            sheets: response.data.sheets?.map((sheet) => sheet.properties),
+        };
+    }
+    async getSheetValues(input) {
+        const response = await this.sheets.spreadsheets.values.get({
+            spreadsheetId: input.spreadsheet_id,
+            range: input.range,
+        });
+        return {
+            range: response.data.range,
+            majorDimension: response.data.majorDimension,
+            values: response.data.values ?? [],
+        };
+    }
+    async updateSheetValues(input) {
+        const response = await this.sheets.spreadsheets.values.update({
+            spreadsheetId: input.spreadsheet_id,
+            range: input.range,
+            valueInputOption: input.value_input_option,
+            requestBody: {
+                values: input.values,
+            },
+        });
+        return response.data;
+    }
+    async appendSheetValues(input) {
+        const response = await this.sheets.spreadsheets.values.append({
+            spreadsheetId: input.spreadsheet_id,
+            range: input.range,
+            valueInputOption: input.value_input_option,
+            insertDataOption: input.insert_data_option,
+            requestBody: {
+                values: input.values,
+            },
+        });
+        return response.data;
+    }
+    extractDocumentText(content) {
+        return content
+            .flatMap((element) => element.paragraph?.elements ?? [])
+            .map((element) => element.textRun?.content ?? "")
+            .join("");
+    }
+    textResponse(data) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return String(error);
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error(`${SERVER_NAME} running on stdio`);
+    }
+}
+const server = new GoogleWorkspaceApiMcpServer();
+server.run().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "google-workspace-api-mcp",
+  "version": "1.0.0",
+  "description": "Google Workspace MCP server for Google Drive, Docs, and Sheets",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "google-workspace-api-mcp": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "ts-node --esm src/index.ts",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "google-docs",
+    "google-sheets",
+    "google-drive",
+    "google-workspace"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "googleapis": "^144.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.3"
+  }
+}