mcp-google-docs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# MCP Google Docs
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+Lightweight MCP Server for querying, reading, and modifying Google Drive documents and spreadsheets.
+
+### Setup
+
+#### 1. Create Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project
+3. Enable Google Drive API, Google Docs API, Google Sheets API
+4. Create OAuth 2.0 credentials (Desktop app type)
+5. Save your Client ID and Client Secret
+
+#### 2. Configure MCP Client
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "google-docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-docs"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your_client_id",
+        "GOOGLE_CLIENT_SECRET": "your_client_secret"
+      }
+    }
+  }
+}
+```
+
+#### 3. First Use
+
+Call `auth_login` tool, browser will open Google authorization page.
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `auth_login` | OAuth login |
+| `auth_status` | Check auth status |
+| `gdrive_list` | List files |
+| `gdrive_search` | Search files |
+| `gdrive_info` | Get file info |
+| `gdocs_read` | Read document |
+| `gdocs_insert` | Insert text |
+| `gdocs_append` | Append text |
+| `gdocs_replace` | Find and replace |
+| `gsheets_info` | Get spreadsheet info |
+| `gsheets_read` | Read sheet |
+| `gsheets_update` | Update cells |
+| `gsheets_batch_update` | Batch update |
+| `gsheets_append_row` | Append row |
+
+### Prompt Template
+
+```markdown
+## Google Docs MCP Rules
+
+### Workflow
+1. Run auth_login first if not authenticated
+2. Use gdrive_search or gdrive_list to find files
+3. Use read/update tools to operate
+
+### Required
+- Always read before modifying
+- Use batch_update for bulk operations
+
+### Forbidden
+- Never guess file IDs, always search first
+- Never update more than 100 cells at once
+```
+
+---
+
+## 中文
+
+轻量级 MCP Server，支持查询、阅读、修改 Google Drive 中的文档和表格。
+
+### 安装配置
+
+#### 1. 创建 Google Cloud 项目
+
+1. 访问 [Google Cloud Console](https://console.cloud.google.com/)
+2. 创建新项目
+3. 启用 Google Drive API、Google Docs API、Google Sheets API
+4. 创建 OAuth 2.0 凭据（桌面应用类型）
+5. 记录 Client ID 和 Client Secret
+
+#### 2. 配置 MCP 客户端
+
+在 Claude Desktop 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "google-docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-docs"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your_client_id",
+        "GOOGLE_CLIENT_SECRET": "your_client_secret"
+      }
+    }
+  }
+}
+```
+
+#### 3. 首次使用
+
+调用 `auth_login` 工具，浏览器会弹出 Google 授权页面，授权后即可使用。
+
+### 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `auth_login` | OAuth 授权登录 |
+| `auth_status` | 检查授权状态 |
+| `gdrive_list` | 列出文件 |
+| `gdrive_search` | 搜索文件 |
+| `gdrive_info` | 获取文件信息 |
+| `gdocs_read` | 读取文档 |
+| `gdocs_insert` | 插入文本 |
+| `gdocs_append` | 追加文本 |
+| `gdocs_replace` | 查找替换 |
+| `gsheets_info` | 获取表格信息 |
+| `gsheets_read` | 读取表格 |
+| `gsheets_update` | 更新单元格 |
+| `gsheets_batch_update` | 批量更新 |
+| `gsheets_append_row` | 追加行 |
+
+### 使用提示词
+
+```markdown
+## Google Docs MCP 使用规则
+
+### 流程
+1. 首次使用先调用 auth_login 授权
+2. 用 gdrive_search 或 gdrive_list 找到目标文件
+3. 用对应的 read/update 工具操作
+
+### 强制
+- 修改前必须先读取确认内容
+- 批量操作使用 batch_update
+
+### 禁止
+- 不要猜测文件ID，必须先搜索
+- 不要一次修改超过100个单元格
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import { OAuth2Client } from 'google-auth-library';
+import { GoogleClients } from './types.js';
+export declare function authenticate(): Promise<OAuth2Client>;
+export declare function startAuthFlow(): Promise<string>;
+export declare function getClients(): Promise<GoogleClients>;
+export declare function isAuthenticated(): boolean;

package/dist/auth.js

@@ -0,0 +1,127 @@
+import { google } from 'googleapis';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as http from 'http';
+import { URL } from 'url';
+import open from 'open';
+import { SCOPES } from './types.js';
+const TOKEN_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.mcp-google-docs');
+const TOKEN_PATH = path.join(TOKEN_DIR, 'token.json');
+let oauth2Client = null;
+function getCredentials() {
+    const clientId = process.env.GOOGLE_CLIENT_ID;
+    const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error('Missing GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET environment variables');
+    }
+    return { clientId, clientSecret };
+}
+function createOAuth2Client() {
+    const { clientId, clientSecret } = getCredentials();
+    return new google.auth.OAuth2(clientId, clientSecret, 'http://localhost:3000/callback');
+}
+function loadToken() {
+    try {
+        if (fs.existsSync(TOKEN_PATH)) {
+            const content = fs.readFileSync(TOKEN_PATH, 'utf-8');
+            return JSON.parse(content);
+        }
+    }
+    catch (error) {
+        console.error('Error loading token:', error);
+    }
+    return null;
+}
+function saveToken(token) {
+    try {
+        if (!fs.existsSync(TOKEN_DIR)) {
+            fs.mkdirSync(TOKEN_DIR, { recursive: true });
+        }
+        fs.writeFileSync(TOKEN_PATH, JSON.stringify(token, null, 2));
+    }
+    catch (error) {
+        console.error('Error saving token:', error);
+    }
+}
+export async function authenticate() {
+    if (oauth2Client) {
+        return oauth2Client;
+    }
+    oauth2Client = createOAuth2Client();
+    const token = loadToken();
+    if (token) {
+        oauth2Client.setCredentials(token);
+        if (token.expiry_date && token.expiry_date < Date.now()) {
+            try {
+                const { credentials } = await oauth2Client.refreshAccessToken();
+                oauth2Client.setCredentials(credentials);
+                saveToken(credentials);
+            }
+            catch (error) {
+                oauth2Client = null;
+                throw new Error('Token expired. Please run auth_login again.');
+            }
+        }
+        return oauth2Client;
+    }
+    throw new Error('Not authenticated. Please run auth_login first.');
+}
+export async function startAuthFlow() {
+    const client = createOAuth2Client();
+    const authUrl = client.generateAuthUrl({
+        access_type: 'offline',
+        scope: SCOPES,
+        prompt: 'consent',
+    });
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(async (req, res) => {
+            try {
+                const url = new URL(req.url, `http://localhost:3000`);
+                if (url.pathname === '/callback') {
+                    const code = url.searchParams.get('code');
+                    if (code) {
+                        const { tokens } = await client.getToken(code);
+                        client.setCredentials(tokens);
+                        saveToken(tokens);
+                        oauth2Client = client;
+                        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                        res.end('<html><body><h1>授权成功！</h1><p>您可以关闭此窗口。</p></body></html>');
+                        server.close();
+                        resolve('Authentication successful! Token saved.');
+                    }
+                    else {
+                        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                        res.end('<html><body><h1>授权失败</h1></body></html>');
+                        server.close();
+                        reject(new Error('No authorization code received'));
+                    }
+                }
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end('<html><body><h1>错误</h1></body></html>');
+                server.close();
+                reject(error);
+            }
+        });
+        server.listen(3000, async () => {
+            console.error('Opening browser for authentication...');
+            await open(authUrl);
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new Error('Authentication timeout (60s)'));
+        }, 60000);
+    });
+}
+export async function getClients() {
+    const auth = await authenticate();
+    return {
+        drive: google.drive({ version: 'v3', auth }),
+        docs: google.docs({ version: 'v1', auth }),
+        sheets: google.sheets({ version: 'v4', auth }),
+    };
+}
+export function isAuthenticated() {
+    return loadToken() !== null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { startAuthFlow, isAuthenticated } from './auth.js';
+import { listFiles, searchFiles, getFileInfo } from './tools/drive.js';
+import { readDocument, insertText, replaceText, appendText } from './tools/docs.js';
+import { readSheet, getSheetInfo, updateCell, updateRange, batchUpdate, appendRow } from './tools/sheets.js';
+const server = new Server({ name: 'mcp-google-docs', version: '1.0.0' }, { capabilities: { tools: {} } });
+// Tool definitions
+const TOOLS = [
+    {
+        name: 'auth_login',
+        description: 'Authenticate with Google. Opens browser for OAuth login. Run this first if not authenticated.',
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'auth_status',
+        description: 'Check if authenticated with Google.',
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'gdrive_list',
+        description: 'List files in Google Drive. Optionally filter by folder.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                folderId: { type: 'string', description: 'Folder ID to list files from (optional)' },
+                pageSize: { type: 'number', description: 'Number of files to return (default: 20)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'gdrive_search',
+        description: 'Search for files in Google Drive by name.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query (file name)' },
+                fileType: { type: 'string', enum: ['document', 'spreadsheet', 'folder'], description: 'Filter by file type' },
+                pageSize: { type: 'number', description: 'Number of results (default: 20)' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'gdrive_info',
+        description: 'Get information about a specific file.',
+        inputSchema: {
+            type: 'object',
+            properties: { fileId: { type: 'string', description: 'File ID' } },
+            required: ['fileId'],
+        },
+    },
+    {
+        name: 'gdocs_read',
+        description: 'Read content from a Google Doc.',
+        inputSchema: {
+            type: 'object',
+            properties: { documentId: { type: 'string', description: 'Document ID' } },
+            required: ['documentId'],
+        },
+    },
+    {
+        name: 'gdocs_insert',
+        description: 'Insert text into a Google Doc at a specific position.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                documentId: { type: 'string', description: 'Document ID' },
+                text: { type: 'string', description: 'Text to insert' },
+                index: { type: 'number', description: 'Position to insert (default: 1, start of doc)' },
+            },
+            required: ['documentId', 'text'],
+        },
+    },
+    {
+        name: 'gdocs_append',
+        description: 'Append text to the end of a Google Doc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                documentId: { type: 'string', description: 'Document ID' },
+                text: { type: 'string', description: 'Text to append' },
+            },
+            required: ['documentId', 'text'],
+        },
+    },
+    {
+        name: 'gdocs_replace',
+        description: 'Find and replace text in a Google Doc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                documentId: { type: 'string', description: 'Document ID' },
+                searchText: { type: 'string', description: 'Text to find' },
+                replaceText: { type: 'string', description: 'Text to replace with' },
+                matchCase: { type: 'boolean', description: 'Case sensitive (default: false)' },
+            },
+            required: ['documentId', 'searchText', 'replaceText'],
+        },
+    },
+    {
+        name: 'gsheets_info',
+        description: 'Get spreadsheet info including sheet names.',
+        inputSchema: {
+            type: 'object',
+            properties: { spreadsheetId: { type: 'string', description: 'Spreadsheet ID' } },
+            required: ['spreadsheetId'],
+        },
+    },
+    {
+        name: 'gsheets_read',
+        description: 'Read data from a Google Sheet range.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                spreadsheetId: { type: 'string', description: 'Spreadsheet ID' },
+                range: { type: 'string', description: 'Range in A1 notation (e.g., Sheet1!A1:D10)' },
+            },
+            required: ['spreadsheetId', 'range'],
+        },
+    },
+    {
+        name: 'gsheets_update',
+        description: 'Update a single cell or range in a Google Sheet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                spreadsheetId: { type: 'string', description: 'Spreadsheet ID' },
+                range: { type: 'string', description: 'Range in A1 notation (e.g., Sheet1!A1)' },
+                value: { type: 'string', description: 'Value to set (for single cell)' },
+                values: { type: 'array', description: 'Array of arrays for range update' },
+            },
+            required: ['spreadsheetId', 'range'],
+        },
+    },
+    {
+        name: 'gsheets_batch_update',
+        description: 'Batch update multiple cells in a Google Sheet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                spreadsheetId: { type: 'string', description: 'Spreadsheet ID' },
+                sheetName: { type: 'string', description: 'Sheet name' },
+                updates: {
+                    type: 'array',
+                    description: 'Array of {row, col, value} objects. Row/col are 1-indexed.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            row: { type: 'number' },
+                            col: { type: 'number' },
+                            value: { type: ['string', 'number', 'boolean'] },
+                        },
+                    },
+                },
+            },
+            required: ['spreadsheetId', 'sheetName', 'updates'],
+        },
+    },
+    {
+        name: 'gsheets_append_row',
+        description: 'Append a new row to a Google Sheet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                spreadsheetId: { type: 'string', description: 'Spreadsheet ID' },
+                sheetName: { type: 'string', description: 'Sheet name' },
+                values: { type: 'array', description: 'Array of values for the new row' },
+            },
+            required: ['spreadsheetId', 'sheetName', 'values'],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+// Tool call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'auth_login': {
+                const result = await startAuthFlow();
+                return { content: [{ type: 'text', text: result }] };
+            }
+            case 'auth_status': {
+                const authenticated = isAuthenticated();
+                return {
+                    content: [{ type: 'text', text: authenticated ? 'Authenticated' : 'Not authenticated. Run auth_login first.' }]
+                };
+            }
+            case 'gdrive_list': {
+                const files = await listFiles(args?.folderId, args?.pageSize);
+                return { content: [{ type: 'text', text: JSON.stringify(files, null, 2) }] };
+            }
+            case 'gdrive_search': {
+                const files = await searchFiles(args.query, args?.fileType, args?.pageSize);
+                return { content: [{ type: 'text', text: JSON.stringify(files, null, 2) }] };
+            }
+            case 'gdrive_info': {
+                const info = await getFileInfo(args.fileId);
+                return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
+            }
+            case 'gdocs_read': {
+                const content = await readDocument(args.documentId);
+                return { content: [{ type: 'text', text: content }] };
+            }
+            case 'gdocs_insert': {
+                await insertText(args.documentId, args.text, args?.index);
+                return { content: [{ type: 'text', text: 'Text inserted successfully' }] };
+            }
+            case 'gdocs_append': {
+                await appendText(args.documentId, args.text);
+                return { content: [{ type: 'text', text: 'Text appended successfully' }] };
+            }
+            case 'gdocs_replace': {
+                const count = await replaceText(args.documentId, args.searchText, args.replaceText, args?.matchCase);
+                return { content: [{ type: 'text', text: `Replaced ${count} occurrence(s)` }] };
+            }
+            case 'gsheets_info': {
+                const info = await getSheetInfo(args.spreadsheetId);
+                return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
+            }
+            case 'gsheets_read': {
+                const data = await readSheet(args.spreadsheetId, args.range);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'gsheets_update': {
+                if (args?.values) {
+                    await updateRange(args.spreadsheetId, args.range, args.values);
+                }
+                else {
+                    await updateCell(args.spreadsheetId, args.range, args.value);
+                }
+                return { content: [{ type: 'text', text: 'Updated successfully' }] };
+            }
+            case 'gsheets_batch_update': {
+                const count = await batchUpdate(args.spreadsheetId, args.sheetName, args.updates);
+                return { content: [{ type: 'text', text: `Updated ${count} cell(s)` }] };
+            }
+            case 'gsheets_append_row': {
+                await appendRow(args.spreadsheetId, args.sheetName, args.values);
+                return { content: [{ type: 'text', text: 'Row appended successfully' }] };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('MCP Google Docs server running on stdio');
+}
+main().catch(console.error);

package/dist/tools/docs.d.ts

@@ -0,0 +1,4 @@
+export declare function readDocument(documentId: string): Promise<string>;
+export declare function insertText(documentId: string, text: string, index?: number): Promise<void>;
+export declare function replaceText(documentId: string, searchText: string, replaceText: string, matchCase?: boolean): Promise<number>;
+export declare function appendText(documentId: string, text: string): Promise<void>;

package/dist/tools/docs.js

@@ -0,0 +1,96 @@
+import { getClients } from '../auth.js';
+export async function readDocument(documentId) {
+    const { docs } = await getClients();
+    const response = await docs.documents.get({ documentId });
+    const document = response.data;
+    let text = '';
+    if (document.body?.content) {
+        for (const element of document.body.content) {
+            if (element.paragraph?.elements) {
+                for (const elem of element.paragraph.elements) {
+                    if (elem.textRun?.content) {
+                        text += elem.textRun.content;
+                    }
+                }
+            }
+            if (element.table) {
+                text += '\n[TABLE]\n';
+                for (const row of element.table.tableRows || []) {
+                    const cells = [];
+                    for (const cell of row.tableCells || []) {
+                        let cellText = '';
+                        for (const content of cell.content || []) {
+                            if (content.paragraph?.elements) {
+                                for (const elem of content.paragraph.elements) {
+                                    if (elem.textRun?.content) {
+                                        cellText += elem.textRun.content.trim();
+                                    }
+                                }
+                            }
+                        }
+                        cells.push(cellText);
+                    }
+                    text += cells.join(' | ') + '\n';
+                }
+                text += '[/TABLE]\n';
+            }
+        }
+    }
+    return text;
+}
+export async function insertText(documentId, text, index) {
+    const { docs } = await getClients();
+    const insertIndex = index ?? 1;
+    await docs.documents.batchUpdate({
+        documentId,
+        requestBody: {
+            requests: [
+                {
+                    insertText: {
+                        location: { index: insertIndex },
+                        text,
+                    },
+                },
+            ],
+        },
+    });
+}
+export async function replaceText(documentId, searchText, replaceText, matchCase = false) {
+    const { docs } = await getClients();
+    const response = await docs.documents.batchUpdate({
+        documentId,
+        requestBody: {
+            requests: [
+                {
+                    replaceAllText: {
+                        containsText: {
+                            text: searchText,
+                            matchCase,
+                        },
+                        replaceText,
+                    },
+                },
+            ],
+        },
+    });
+    const replies = response.data.replies || [];
+    return replies[0]?.replaceAllText?.occurrencesChanged || 0;
+}
+export async function appendText(documentId, text) {
+    const { docs } = await getClients();
+    const doc = await docs.documents.get({ documentId });
+    const endIndex = doc.data.body?.content?.slice(-1)[0]?.endIndex || 1;
+    await docs.documents.batchUpdate({
+        documentId,
+        requestBody: {
+            requests: [
+                {
+                    insertText: {
+                        location: { index: endIndex - 1 },
+                        text,
+                    },
+                },
+            ],
+        },
+    });
+}

package/dist/tools/drive.d.ts

@@ -0,0 +1,4 @@
+import { DriveFile } from '../types.js';
+export declare function listFiles(folderId?: string, pageSize?: number): Promise<DriveFile[]>;
+export declare function searchFiles(query: string, fileType?: 'document' | 'spreadsheet' | 'folder', pageSize?: number): Promise<DriveFile[]>;
+export declare function getFileInfo(fileId: string): Promise<DriveFile>;