gdocs-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apurwa Sarwajit
+
+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,94 @@
+# gdocs-mcp
+
+Open-source MCP server for Google Docs and Sheets. Give Claude (or any MCP-compatible AI) the ability to read, create, edit, and search your Google Docs — with OAuth tokens that never leave your machine.
+
+**Like Composio, but open-source and self-hosted.**
+
+## Quick Start
+
+### 1. Set up Google Cloud credentials (one-time)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create a project (or use an existing one)
+3. Enable the **Google Docs API**, **Google Sheets API**, and **Google Drive API**
+4. Go to **Google Auth Platform** > **Audience**, set to External, add yourself as a test user
+5. Go to **Credentials** > **Create Credentials** > **OAuth client ID** > **Desktop app**
+6. Download the JSON file
+
+### 2. Authenticate
+
+```bash
+npx gdocs-mcp auth ~/Downloads/client_secret_*.json
+```
+
+This opens your browser for Google sign-in, saves the token to `~/.gdocs-mcp/`, and prints the MCP config.
+
+### 3. Add to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "gdocs": {
+      "command": "npx",
+      "args": ["gdocs-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask Claude: *"List my recent Google Docs"* to verify.
+
+### Add to Claude Code
+
+```bash
+claude mcp add gdocs -- npx gdocs-mcp
+```
+
+## Tools
+
+### Google Docs
+
+| Tool | Description |
+|------|-------------|
+| `read_document` | Read the full content of a Google Doc |
+| `search_documents` | Search Google Drive for documents by name, content, or date |
+| `create_document` | Create a new Google Doc with optional Markdown content |
+| `replace_all_text` | Find and replace all occurrences of text in a document |
+| `replace_image` | Replace an existing image with a new image from a URI |
+| `update_document_markdown` | Replace the entire document body with Markdown |
+| `update_document_section_markdown` | Insert or replace a section by index with Markdown |
+| `update_document_style` | Update page size, margins, text direction |
+| `update_document` | Raw batchUpdate with 35+ request types |
+| `unmerge_table_cells` | Unmerge previously merged table cells |
+
+### Google Sheets
+
+| Tool | Description |
+|------|-------------|
+| `get_charts` | List all charts in a spreadsheet with IDs and specs |
+
+## Security
+
+- OAuth tokens are stored locally at `~/.gdocs-mcp/token.json` with `600` permissions
+- Credentials are stored at `~/.gdocs-mcp/credentials.json` with `600` permissions
+- No telemetry, no data collection, no third-party token storage
+- Tokens refresh automatically; if refresh fails, run `npx gdocs-mcp auth` again
+
+## Configuration
+
+By default, credentials and tokens are stored in `~/.gdocs-mcp/`. Override with:
+
+```bash
+GDOCS_CREDENTIALS=/path/to/credentials.json npx gdocs-mcp
+```
+
+## Requirements
+
+- Node.js 18+
+- A Google Cloud project with Docs, Sheets, and Drive APIs enabled
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+
+if (args[0] === 'auth') {
+  const authArgs = args.slice(1);
+  process.argv = [process.argv[0], process.argv[1], ...authArgs];
+  await import('../dist/auth/cli.js');
+} else {
+  await import('../dist/index.js');
+}

package/dist/auth/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * One-time OAuth flow. Run: npx gdocs-mcp auth
+ * Copies credentials to ~/.gdocs-mcp/ and saves OAuth token.
+ */
+export {};

package/dist/auth/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * One-time OAuth flow. Run: npx gdocs-mcp auth
+ * Copies credentials to ~/.gdocs-mcp/ and saves OAuth token.
+ */
+import { google } from 'googleapis';
+import fs from 'fs';
+import http from 'http';
+import path from 'path';
+import { CONFIG_DIR, TOKEN_PATH, CREDENTIALS_PATH_DEFAULT, getScopes } from './google-auth.js';
+async function main() {
+    // Ensure config directory exists
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+    // Find credentials.json
+    const args = process.argv.slice(2);
+    let inputCredPath = args[0];
+    if (!inputCredPath) {
+        // Check default location first
+        if (fs.existsSync(CREDENTIALS_PATH_DEFAULT)) {
+            console.log(`Using existing credentials at ${CREDENTIALS_PATH_DEFAULT}`);
+            inputCredPath = CREDENTIALS_PATH_DEFAULT;
+        }
+        else {
+            console.error('Usage: npx gdocs-mcp auth [path/to/credentials.json]');
+            console.error('');
+            console.error('Download credentials.json from Google Cloud Console:');
+            console.error('  1. Go to console.cloud.google.com/apis/credentials');
+            console.error('  2. Create OAuth 2.0 Client ID (Desktop app)');
+            console.error('  3. Download JSON');
+            process.exit(1);
+        }
+    }
+    // Resolve and validate credentials
+    const resolvedPath = path.resolve(inputCredPath.replace('~', process.env.HOME || ''));
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(`File not found: ${resolvedPath}`);
+        process.exit(1);
+    }
+    const raw = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+    const creds = raw.installed || raw.web;
+    if (!creds?.client_id || !creds?.client_secret) {
+        console.error('Invalid credentials file. Expected OAuth 2.0 client credentials with client_id and client_secret.');
+        console.error('Make sure you downloaded the OAuth client JSON, not an API key or service account.');
+        process.exit(1);
+    }
+    // Copy credentials to config dir if not already there
+    if (resolvedPath !== CREDENTIALS_PATH_DEFAULT) {
+        fs.copyFileSync(resolvedPath, CREDENTIALS_PATH_DEFAULT);
+        fs.chmodSync(CREDENTIALS_PATH_DEFAULT, 0o600);
+        console.log(`Credentials copied to ${CREDENTIALS_PATH_DEFAULT}`);
+    }
+    // Set up OAuth client
+    const oAuth2Client = new google.auth.OAuth2(creds.client_id, creds.client_secret, 'http://localhost:3333');
+    const authUrl = oAuth2Client.generateAuthUrl({
+        access_type: 'offline',
+        scope: getScopes(),
+        prompt: 'consent',
+    });
+    console.log('\nOpening browser for Google authorization...');
+    // Start local server to catch the redirect
+    const server = http.createServer(async (req, res) => {
+        const reqUrl = new URL(req.url || '', 'http://localhost:3333');
+        const code = reqUrl.searchParams.get('code') || undefined;
+        if (!code) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end('<h2>No authorization code received.</h2>');
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`
+      <html>
+        <body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0;">
+          <div style="text-align: center;">
+            <h2>Auth complete!</h2>
+            <p>You can close this tab and return to your terminal.</p>
+          </div>
+        </body>
+      </html>
+    `);
+        server.close();
+        try {
+            const { tokens } = await oAuth2Client.getToken(code);
+            fs.writeFileSync(TOKEN_PATH, JSON.stringify(tokens, null, 2));
+            fs.chmodSync(TOKEN_PATH, 0o600);
+            console.log(`\nToken saved to ${TOKEN_PATH}`);
+            console.log('\nSetup complete! Add this to your MCP config:\n');
+            console.log(JSON.stringify({
+                mcpServers: {
+                    gdocs: {
+                        command: 'npx',
+                        args: ['gdocs-mcp'],
+                    }
+                }
+            }, null, 2));
+            console.log('');
+            process.exit(0);
+        }
+        catch (err) {
+            console.error('Failed to exchange authorization code:', err);
+            process.exit(1);
+        }
+    });
+    server.listen(3333, async () => {
+        // Open browser
+        const { exec } = await import('child_process');
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${cmd} "${authUrl}"`, (err) => {
+            if (err) {
+                console.log('\nCould not open browser automatically. Open this URL:\n');
+                console.log(authUrl);
+                console.log('');
+            }
+        });
+    });
+}
+main().catch((err) => {
+    console.error('Auth failed:', err.message);
+    process.exit(1);
+});

package/dist/auth/google-auth.d.ts

@@ -0,0 +1,9 @@
+import { OAuth2Client } from 'google-auth-library';
+declare const CONFIG_DIR: string;
+declare const TOKEN_PATH: string;
+declare const CREDENTIALS_PATH_DEFAULT: string;
+export declare function getAuthClient(): OAuth2Client;
+export declare function getConfigDir(): string;
+export declare function getTokenPath(): string;
+export declare function getScopes(): string[];
+export { CONFIG_DIR, TOKEN_PATH, CREDENTIALS_PATH_DEFAULT };

package/dist/auth/google-auth.js

@@ -0,0 +1,51 @@
+import { google } from 'googleapis';
+import fs from 'fs';
+import path from 'path';
+const CONFIG_DIR = path.join(process.env.HOME || '~', '.gdocs-mcp');
+const TOKEN_PATH = path.join(CONFIG_DIR, 'token.json');
+const CREDENTIALS_PATH_DEFAULT = path.join(CONFIG_DIR, 'credentials.json');
+const SCOPES = [
+    'https://www.googleapis.com/auth/documents',
+    'https://www.googleapis.com/auth/spreadsheets.readonly',
+    'https://www.googleapis.com/auth/drive.readonly',
+];
+function getCredentialsPath() {
+    return process.env.GDOCS_CREDENTIALS || CREDENTIALS_PATH_DEFAULT;
+}
+function loadCredentials() {
+    const credPath = getCredentialsPath();
+    if (!fs.existsSync(credPath)) {
+        throw new Error(`Credentials not found at ${credPath}. Run: npx gdocs-mcp auth`);
+    }
+    const raw = JSON.parse(fs.readFileSync(credPath, 'utf8'));
+    const creds = raw.installed || raw.web;
+    if (!creds) {
+        throw new Error('Invalid credentials.json format. Expected "installed" or "web" key.');
+    }
+    return creds;
+}
+export function getAuthClient() {
+    const creds = loadCredentials();
+    const oAuth2Client = new google.auth.OAuth2(creds.client_id, creds.client_secret, 'http://localhost:3333');
+    if (!fs.existsSync(TOKEN_PATH)) {
+        throw new Error('Auth required. Run: npx gdocs-mcp auth');
+    }
+    const token = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+    oAuth2Client.setCredentials(token);
+    oAuth2Client.on('tokens', (newTokens) => {
+        const existing = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+        const merged = { ...existing, ...newTokens };
+        fs.writeFileSync(TOKEN_PATH, JSON.stringify(merged, null, 2));
+    });
+    return oAuth2Client;
+}
+export function getConfigDir() {
+    return CONFIG_DIR;
+}
+export function getTokenPath() {
+    return TOKEN_PATH;
+}
+export function getScopes() {
+    return SCOPES;
+}
+export { CONFIG_DIR, TOKEN_PATH, CREDENTIALS_PATH_DEFAULT };

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ReadDocumentSchema, readDocument } from './tools/read-document.js';
+import { SearchDocumentsSchema, searchDocuments } from './tools/search-documents.js';
+import { CreateDocumentSchema, createDocument } from './tools/create-document.js';
+import { ReplaceAllTextSchema, replaceAllText } from './tools/replace-all-text.js';
+import { ReplaceImageSchema, replaceImage } from './tools/replace-image.js';
+import { UpdateDocumentMarkdownSchema, updateDocumentMarkdown } from './tools/update-document-markdown.js';
+import { UpdateDocumentSectionMarkdownSchema, updateDocumentSectionMarkdown } from './tools/update-document-section-markdown.js';
+import { UpdateDocumentStyleSchema, updateDocumentStyle } from './tools/update-document-style.js';
+import { UpdateDocumentSchema, updateDocument } from './tools/update-document.js';
+import { UnmergeTableCellsSchema, unmergeTableCells } from './tools/unmerge-table-cells.js';
+import { GetChartsSchema, getCharts } from './tools/get-charts.js';
+const server = new McpServer({
+    name: 'gdocs-mcp',
+    version: '0.1.0',
+});
+function formatError(err) {
+    if (err instanceof Error) {
+        const message = err.message;
+        if (message.includes('not found') || message.includes('404')) {
+            return 'Document not found. Check the document ID and ensure it is shared with your account.';
+        }
+        if (message.includes('UNAUTHENTICATED') || message.includes('invalid_grant')) {
+            return 'Auth expired. Run: npx gdocs-mcp auth';
+        }
+        if (message.includes('RATE_LIMIT') || message.includes('429')) {
+            return 'Google API quota exceeded. Wait 60 seconds and retry.';
+        }
+        if (message.includes('PERMISSION_DENIED') || message.includes('403')) {
+            return 'Permission denied. Ensure the document is shared with your Google account.';
+        }
+        return message;
+    }
+    return String(err);
+}
+function registerTool(name, description, schema, handler) {
+    server.tool(name, description, schema.shape, async (args) => {
+        try {
+            const result = await handler(args);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: formatError(err) }],
+                isError: true,
+            };
+        }
+    });
+}
+// Google Docs tools
+registerTool('read_document', 'Read the full content of a Google Doc', ReadDocumentSchema, readDocument);
+registerTool('search_documents', 'Search Google Drive for documents by name, content, or date', SearchDocumentsSchema, searchDocuments);
+registerTool('create_document', 'Create a new Google Doc with optional Markdown content', CreateDocumentSchema, createDocument);
+registerTool('replace_all_text', 'Find and replace all occurrences of text in a document', ReplaceAllTextSchema, replaceAllText);
+registerTool('replace_image', 'Replace an existing image in a document with a new image from a URI', ReplaceImageSchema, replaceImage);
+registerTool('update_document_markdown', 'Replace the entire document body with Markdown content', UpdateDocumentMarkdownSchema, updateDocumentMarkdown);
+registerTool('update_document_section_markdown', 'Insert or replace a section of a document with Markdown content', UpdateDocumentSectionMarkdownSchema, updateDocumentSectionMarkdown);
+registerTool('update_document_style', 'Update document style: page size, margins, text direction', UpdateDocumentStyleSchema, updateDocumentStyle);
+registerTool('update_document', 'Apply batch updates to a document (insertText, updateTextStyle, createParagraphBullets, insertTable, etc.)', UpdateDocumentSchema, updateDocument);
+registerTool('unmerge_table_cells', 'Unmerge previously merged cells in a document table', UnmergeTableCellsSchema, unmergeTableCells);
+// Google Sheets tools
+registerTool('get_charts', 'List all charts in a Google Sheets spreadsheet with IDs and specs', GetChartsSchema, getCharts);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('gdocs-mcp v0.1.0 started');
+}
+main().catch((err) => {
+    console.error('Failed to start gdocs-mcp:', err);
+    process.exit(1);
+});

package/dist/tools/create-document.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const CreateDocumentSchema: z.ZodObject<{
+    title: z.ZodString;
+    markdown: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function createDocument(args: z.infer<typeof CreateDocumentSchema>): Promise<{
+    documentId: string;
+    title: string;
+    url: string;
+}>;

package/dist/tools/create-document.js

@@ -0,0 +1,37 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const CreateDocumentSchema = z.object({
+    title: z.string().describe('Title for the new Google Doc'),
+    markdown: z.string().optional().describe('Optional Markdown content to populate the document with'),
+});
+export async function createDocument(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    // Create empty doc
+    const createRes = await docs.documents.create({
+        requestBody: { title: args.title },
+    });
+    const documentId = createRes.data.documentId;
+    // If markdown provided, insert it as text content
+    if (args.markdown) {
+        await docs.documents.batchUpdate({
+            documentId,
+            requestBody: {
+                requests: [
+                    {
+                        insertText: {
+                            location: { index: 1 },
+                            text: args.markdown,
+                        },
+                    },
+                ],
+            },
+        });
+    }
+    return {
+        documentId,
+        title: args.title,
+        url: `https://docs.google.com/document/d/${documentId}/edit`,
+    };
+}

package/dist/tools/get-charts.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const GetChartsSchema: z.ZodObject<{
+    spreadsheetId: z.ZodString;
+}, z.core.$strip>;
+export declare function getCharts(args: z.infer<typeof GetChartsSchema>): Promise<{
+    spreadsheetId: string;
+    charts: any[];
+    count: number;
+}>;

package/dist/tools/get-charts.js

@@ -0,0 +1,30 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const GetChartsSchema = z.object({
+    spreadsheetId: z.string().describe('The Google Sheets spreadsheet ID (from the URL)'),
+});
+export async function getCharts(args) {
+    const auth = getAuthClient();
+    const sheets = google.sheets({ version: 'v4', auth });
+    const res = await sheets.spreadsheets.get({
+        spreadsheetId: args.spreadsheetId,
+        fields: 'sheets(charts(chartId,position,spec))',
+    });
+    const allCharts = [];
+    for (const sheet of res.data.sheets || []) {
+        for (const chart of sheet.charts || []) {
+            allCharts.push({
+                chartId: chart.chartId,
+                title: chart.spec?.title || 'Untitled',
+                chartType: chart.spec?.basicChart?.chartType || chart.spec?.pieChart ? 'PIE' : 'UNKNOWN',
+                position: chart.position,
+            });
+        }
+    }
+    return {
+        spreadsheetId: args.spreadsheetId,
+        charts: allCharts,
+        count: allCharts.length,
+    };
+}

package/dist/tools/read-document.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const ReadDocumentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+}, z.core.$strip>;
+export declare function readDocument(args: z.infer<typeof ReadDocumentSchema>): Promise<{
+    documentId: string;
+    title: string;
+    content: string;
+    revisionId: string | null | undefined;
+}>;

package/dist/tools/read-document.js

@@ -0,0 +1,46 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const ReadDocumentSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID (from the URL)'),
+});
+export async function readDocument(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const res = await docs.documents.get({ documentId: args.documentId });
+    const doc = res.data;
+    const title = doc.title || 'Untitled';
+    const body = doc.body?.content || [];
+    const textContent = extractText(body);
+    return {
+        documentId: args.documentId,
+        title,
+        content: textContent,
+        revisionId: doc.revisionId,
+    };
+}
+function extractText(content) {
+    const parts = [];
+    for (const element of content) {
+        if (element.paragraph) {
+            const paragraphText = element.paragraph.elements
+                ?.map((el) => el.textRun?.content || '')
+                .join('') || '';
+            parts.push(paragraphText);
+        }
+        else if (element.table) {
+            for (const row of element.table.tableRows || []) {
+                const cells = row.tableCells?.map((cell) => {
+                    const cellContent = cell.content || [];
+                    return extractText(cellContent).trim();
+                }) || [];
+                parts.push('| ' + cells.join(' | ') + ' |');
+            }
+            parts.push('');
+        }
+        else if (element.sectionBreak) {
+            parts.push('---');
+        }
+    }
+    return parts.join('');
+}

package/dist/tools/replace-all-text.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare const ReplaceAllTextSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    find: z.ZodString;
+    replaceWith: z.ZodString;
+    matchCase: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare function replaceAllText(args: z.infer<typeof ReplaceAllTextSchema>): Promise<{
+    documentId: string;
+    occurrencesReplaced: number;
+}>;

package/dist/tools/replace-all-text.js

@@ -0,0 +1,34 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const ReplaceAllTextSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    find: z.string().describe('Text to find (all occurrences will be replaced)'),
+    replaceWith: z.string().describe('Replacement text'),
+    matchCase: z.boolean().optional().default(true).describe('Whether the search is case-sensitive (default: true)'),
+});
+export async function replaceAllText(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const res = await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    replaceAllText: {
+                        containsText: {
+                            text: args.find,
+                            matchCase: args.matchCase,
+                        },
+                        replaceText: args.replaceWith,
+                    },
+                },
+            ],
+        },
+    });
+    const replaceResult = res.data.replies?.[0]?.replaceAllText;
+    return {
+        documentId: args.documentId,
+        occurrencesReplaced: replaceResult?.occurrencesChanged || 0,
+    };
+}

package/dist/tools/replace-image.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare const ReplaceImageSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    imageObjectId: z.ZodString;
+    newImageUri: z.ZodString;
+}, z.core.$strip>;
+export declare function replaceImage(args: z.infer<typeof ReplaceImageSchema>): Promise<{
+    documentId: string;
+    imageObjectId: string;
+    replaced: boolean;
+}>;

package/dist/tools/replace-image.js

@@ -0,0 +1,30 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const ReplaceImageSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    imageObjectId: z.string().describe('The object ID of the image to replace (from read_document)'),
+    newImageUri: z.string().url().describe('URI of the new image to insert'),
+});
+export async function replaceImage(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    replaceImage: {
+                        imageObjectId: args.imageObjectId,
+                        uri: args.newImageUri,
+                    },
+                },
+            ],
+        },
+    });
+    return {
+        documentId: args.documentId,
+        imageObjectId: args.imageObjectId,
+        replaced: true,
+    };
+}

package/dist/tools/search-documents.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const SearchDocumentsSchema: z.ZodObject<{
+    query: z.ZodString;
+    dateFrom: z.ZodOptional<z.ZodString>;
+    dateTo: z.ZodOptional<z.ZodString>;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare function searchDocuments(args: z.infer<typeof SearchDocumentsSchema>): Promise<{
+    documentId: string | null | undefined;
+    title: string | null | undefined;
+    lastModified: string | null | undefined;
+    url: string | null | undefined;
+    owner: string;
+}[]>;

package/dist/tools/search-documents.js

@@ -0,0 +1,37 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const SearchDocumentsSchema = z.object({
+    query: z.string().describe('Search query — matches document title and content'),
+    dateFrom: z.string().optional().describe('Filter: modified after this date (ISO 8601, e.g. 2026-01-01)'),
+    dateTo: z.string().optional().describe('Filter: modified before this date (ISO 8601)'),
+    maxResults: z.number().optional().default(10).describe('Maximum number of results to return (default: 10)'),
+});
+export async function searchDocuments(args) {
+    const auth = getAuthClient();
+    const drive = google.drive({ version: 'v3', auth });
+    const queryParts = [
+        "mimeType='application/vnd.google-apps.document'",
+        `fullText contains '${args.query.replace(/'/g, "\\'")}'`,
+    ];
+    if (args.dateFrom) {
+        queryParts.push(`modifiedTime >= '${args.dateFrom}T00:00:00'`);
+    }
+    if (args.dateTo) {
+        queryParts.push(`modifiedTime <= '${args.dateTo}T23:59:59'`);
+    }
+    const res = await drive.files.list({
+        q: queryParts.join(' and '),
+        pageSize: args.maxResults,
+        fields: 'files(id, name, modifiedTime, webViewLink, owners)',
+        orderBy: 'modifiedTime desc',
+    });
+    const files = res.data.files || [];
+    return files.map(f => ({
+        documentId: f.id,
+        title: f.name,
+        lastModified: f.modifiedTime,
+        url: f.webViewLink,
+        owner: f.owners?.[0]?.emailAddress || 'unknown',
+    }));
+}

package/dist/tools/unmerge-table-cells.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const UnmergeTableCellsSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    tableStartIndex: z.ZodNumber;
+    rowIndex: z.ZodNumber;
+    columnIndex: z.ZodNumber;
+}, z.core.$strip>;
+export declare function unmergeTableCells(args: z.infer<typeof UnmergeTableCellsSchema>): Promise<{
+    documentId: string;
+    unmerged: boolean;
+    tableStartIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}>;

package/dist/tools/unmerge-table-cells.js

@@ -0,0 +1,40 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const UnmergeTableCellsSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    tableStartIndex: z.number().describe('The start index of the table in the document body'),
+    rowIndex: z.number().describe('The zero-based row index of the cell to unmerge'),
+    columnIndex: z.number().describe('The zero-based column index of the cell to unmerge'),
+});
+export async function unmergeTableCells(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    unmergeTableCells: {
+                        tableRange: {
+                            tableCellLocation: {
+                                tableStartLocation: { index: args.tableStartIndex },
+                                rowIndex: args.rowIndex,
+                                columnIndex: args.columnIndex,
+                            },
+                            rowSpan: 1,
+                            columnSpan: 1,
+                        },
+                    },
+                },
+            ],
+        },
+    });
+    return {
+        documentId: args.documentId,
+        unmerged: true,
+        tableStartIndex: args.tableStartIndex,
+        rowIndex: args.rowIndex,
+        columnIndex: args.columnIndex,
+    };
+}

package/dist/tools/update-document-markdown.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const UpdateDocumentMarkdownSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    markdown: z.ZodString;
+}, z.core.$strip>;
+export declare function updateDocumentMarkdown(args: z.infer<typeof UpdateDocumentMarkdownSchema>): Promise<{
+    documentId: string;
+    updated: boolean;
+    contentLength: number;
+}>;

package/dist/tools/update-document-markdown.js

@@ -0,0 +1,45 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const UpdateDocumentMarkdownSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    markdown: z.string().describe('Markdown content to replace the entire document body with'),
+});
+export async function updateDocumentMarkdown(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    // Get current document to find end index
+    const current = await docs.documents.get({ documentId: args.documentId });
+    const body = current.data.body;
+    const endIndex = body?.content
+        ? body.content[body.content.length - 1]?.endIndex || 1
+        : 1;
+    const requests = [];
+    // Delete existing content (except the trailing newline at index 1)
+    if (endIndex > 2) {
+        requests.push({
+            deleteContentRange: {
+                range: {
+                    startIndex: 1,
+                    endIndex: endIndex - 1,
+                },
+            },
+        });
+    }
+    // Insert new content
+    requests.push({
+        insertText: {
+            location: { index: 1 },
+            text: args.markdown,
+        },
+    });
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: { requests },
+    });
+    return {
+        documentId: args.documentId,
+        updated: true,
+        contentLength: args.markdown.length,
+    };
+}

package/dist/tools/update-document-section-markdown.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const UpdateDocumentSectionMarkdownSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    markdown: z.ZodString;
+    startIndex: z.ZodNumber;
+    endIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function updateDocumentSectionMarkdown(args: z.infer<typeof UpdateDocumentSectionMarkdownSchema>): Promise<{
+    documentId: string;
+    updated: boolean;
+    startIndex: number;
+    endIndex: number | undefined;
+    insertedLength: number;
+}>;

package/dist/tools/update-document-section-markdown.js

@@ -0,0 +1,43 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const UpdateDocumentSectionMarkdownSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    markdown: z.string().describe('Markdown content to insert or replace within the section'),
+    startIndex: z.number().describe('Start index of the section to replace'),
+    endIndex: z.number().optional().describe('End index of the section. If omitted, content is inserted at startIndex without deleting.'),
+});
+export async function updateDocumentSectionMarkdown(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const requests = [];
+    // Delete the existing section if endIndex is provided
+    if (args.endIndex !== undefined && args.endIndex > args.startIndex) {
+        requests.push({
+            deleteContentRange: {
+                range: {
+                    startIndex: args.startIndex,
+                    endIndex: args.endIndex,
+                },
+            },
+        });
+    }
+    // Insert new content at the start index
+    requests.push({
+        insertText: {
+            location: { index: args.startIndex },
+            text: args.markdown,
+        },
+    });
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: { requests },
+    });
+    return {
+        documentId: args.documentId,
+        updated: true,
+        startIndex: args.startIndex,
+        endIndex: args.endIndex,
+        insertedLength: args.markdown.length,
+    };
+}

package/dist/tools/update-document-style.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export declare const UpdateDocumentStyleSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    pageSize: z.ZodOptional<z.ZodObject<{
+        width: z.ZodOptional<z.ZodObject<{
+            magnitude: z.ZodNumber;
+            unit: z.ZodDefault<z.ZodEnum<{
+                PT: "PT";
+                MM: "MM";
+                INCH: "INCH";
+            }>>;
+        }, z.core.$strip>>;
+        height: z.ZodOptional<z.ZodObject<{
+            magnitude: z.ZodNumber;
+            unit: z.ZodDefault<z.ZodEnum<{
+                PT: "PT";
+                MM: "MM";
+                INCH: "INCH";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    marginTop: z.ZodOptional<z.ZodObject<{
+        magnitude: z.ZodNumber;
+        unit: z.ZodDefault<z.ZodEnum<{
+            PT: "PT";
+            MM: "MM";
+            INCH: "INCH";
+        }>>;
+    }, z.core.$strip>>;
+    marginBottom: z.ZodOptional<z.ZodObject<{
+        magnitude: z.ZodNumber;
+        unit: z.ZodDefault<z.ZodEnum<{
+            PT: "PT";
+            MM: "MM";
+            INCH: "INCH";
+        }>>;
+    }, z.core.$strip>>;
+    marginLeft: z.ZodOptional<z.ZodObject<{
+        magnitude: z.ZodNumber;
+        unit: z.ZodDefault<z.ZodEnum<{
+            PT: "PT";
+            MM: "MM";
+            INCH: "INCH";
+        }>>;
+    }, z.core.$strip>>;
+    marginRight: z.ZodOptional<z.ZodObject<{
+        magnitude: z.ZodNumber;
+        unit: z.ZodDefault<z.ZodEnum<{
+            PT: "PT";
+            MM: "MM";
+            INCH: "INCH";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function updateDocumentStyle(args: z.infer<typeof UpdateDocumentStyleSchema>): Promise<{
+    documentId: string;
+    updated: boolean;
+    reason: string;
+    fieldsUpdated?: undefined;
+} | {
+    documentId: string;
+    updated: boolean;
+    fieldsUpdated: string[];
+    reason?: undefined;
+}>;

package/dist/tools/update-document-style.js

@@ -0,0 +1,72 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+const DimensionSchema = z.object({
+    magnitude: z.number(),
+    unit: z.enum(['PT', 'MM', 'INCH']).default('PT'),
+});
+export const UpdateDocumentStyleSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    pageSize: z.object({
+        width: DimensionSchema.optional(),
+        height: DimensionSchema.optional(),
+    }).optional().describe('Page dimensions'),
+    marginTop: DimensionSchema.optional().describe('Top margin'),
+    marginBottom: DimensionSchema.optional().describe('Bottom margin'),
+    marginLeft: DimensionSchema.optional().describe('Left margin'),
+    marginRight: DimensionSchema.optional().describe('Right margin'),
+});
+export async function updateDocumentStyle(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    const documentStyle = {};
+    const fields = [];
+    if (args.pageSize) {
+        documentStyle.pageSize = {};
+        if (args.pageSize.width) {
+            documentStyle.pageSize.width = args.pageSize.width;
+            fields.push('pageSize.width');
+        }
+        if (args.pageSize.height) {
+            documentStyle.pageSize.height = args.pageSize.height;
+            fields.push('pageSize.height');
+        }
+    }
+    if (args.marginTop) {
+        documentStyle.marginTop = args.marginTop;
+        fields.push('marginTop');
+    }
+    if (args.marginBottom) {
+        documentStyle.marginBottom = args.marginBottom;
+        fields.push('marginBottom');
+    }
+    if (args.marginLeft) {
+        documentStyle.marginLeft = args.marginLeft;
+        fields.push('marginLeft');
+    }
+    if (args.marginRight) {
+        documentStyle.marginRight = args.marginRight;
+        fields.push('marginRight');
+    }
+    if (fields.length === 0) {
+        return { documentId: args.documentId, updated: false, reason: 'No style changes specified' };
+    }
+    await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: {
+            requests: [
+                {
+                    updateDocumentStyle: {
+                        documentStyle,
+                        fields: fields.join(','),
+                    },
+                },
+            ],
+        },
+    });
+    return {
+        documentId: args.documentId,
+        updated: true,
+        fieldsUpdated: fields,
+    };
+}

package/dist/tools/update-document.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const UpdateDocumentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    requests: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+export declare function updateDocument(args: z.infer<typeof UpdateDocumentSchema>): Promise<{
+    documentId: string;
+    repliesCount: number;
+    writeControl: import("googleapis").docs_v1.Schema$WriteControl | undefined;
+}>;

package/dist/tools/update-document.js

@@ -0,0 +1,31 @@
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { getAuthClient } from '../auth/google-auth.js';
+export const UpdateDocumentSchema = z.object({
+    documentId: z.string().describe('The Google Doc document ID'),
+    requests: z.array(z.record(z.string(), z.any())).min(1).describe('Array of Google Docs API batchUpdate requests. ' +
+        'Supported types include: insertText, deleteContentRange, replaceAllText, ' +
+        'updateTextStyle, createParagraphBullets, insertTable, insertInlineImage, ' +
+        'createHeader, createFooter, updateDocumentStyle, and more. ' +
+        'See: https://developers.google.com/docs/api/reference/rest/v1/documents/request'),
+});
+export async function updateDocument(args) {
+    const auth = getAuthClient();
+    const docs = google.docs({ version: 'v1', auth });
+    // Validate each request has exactly one key (the request type)
+    for (const [i, req] of args.requests.entries()) {
+        const keys = Object.keys(req);
+        if (keys.length !== 1) {
+            throw new Error(`Request at index ${i} must have exactly one key (the request type), got: ${keys.join(', ')}`);
+        }
+    }
+    const res = await docs.documents.batchUpdate({
+        documentId: args.documentId,
+        requestBody: { requests: args.requests },
+    });
+    return {
+        documentId: args.documentId,
+        repliesCount: res.data.replies?.length || 0,
+        writeControl: res.data.writeControl,
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "gdocs-mcp",
+  "version": "0.1.0",
+  "description": "Open-source MCP server for Google Docs and Sheets. Self-hosted, local OAuth, no third-party token storage.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "gdocs-mcp": "./bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "google-docs",
+    "google-sheets",
+    "model-context-protocol",
+    "claude",
+    "ai-tools",
+    "google-workspace",
+    "document-automation"
+  ],
+  "author": "Apurwa Sarwajit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apurwa-sudo/gdocs-mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "googleapis": "^171.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}