google-docs-mcp

When using Calendar tools, the calendarId parameter defaults to "primary", which refers to the user's main calendar. To interact with shared or secondary calendars, you must provide the specific calendar ID.

Examples of Calendar ID formats:

• Email addresses: username@example.com
• Group/Secondary calendars: c_abc123def456@group.calendar.google.com

Standard Markdown is insufficient for complex table cells. The RichCellContent model allows for structured, multi-line content within a single cell, supporting:

• Paragraphs: Text blocks with individual TextRun styling (bold, italic, underline, color, links).
• Bulleted Lists: Items containing multiple text runs.
• Numbered Lists: Ordered sequences of text runs.

This enables patterns like a bold label followed by a bulleted list within one cell.

type RichCellContent = {
  blocks: Array<
    | { type: 'paragraph'; runs: TextRun[]; }
    | { type: 'bulletedList'; items: Array<{ runs: TextRun[] }>; }
    | { type: 'numberedList'; items: Array<{ runs: TextRun[] }>; }
  >;
};

type TextRun = {
  text: string;
  bold?: boolean;
  italic?: boolean;
  underline?: boolean;
  foregroundColor?: string;
  linkUrl?: string;
};

Because Google Docs does not expose user-friendly table IDs directly, the MCP layer uses stable identifiers to target specific tables. These identifiers are generated using a combination of the table's start index, its ordinal position in a tab, and optional nearby heading anchors.

Identifier Formats:

• table:t.0:3 (Index and position)
• table:t.0:heading-NAME:0 (Index, position, and heading anchor)

Use these identifiers when calling tools that require a specific table target to ensure your operations (like row replacement or styling) hit the correct element.

When working with complex Google Docs (like planning documents), avoid using full-document Markdown replacement. Markdown is insufficient for rich features like tables, smart chips, and specific cell styling.

Instead, follow a template-aware, table-aware, chip-aware, and patch-based architecture. This ensures that updates to specific sections (like a task table) do not corrupt the rest of the document's formatting or structure.

The server organizes its Model Context Protocol (MCP) tools into domain-specific modules. A top-level router (tools/index.ts) delegates tool registration to individual domain routers. Each domain (e.g., docs, drive, gmail) acts as a sub-module containing its own tools, documentation, and a router that registers those tools with the main server.

Directory Structure:

• tools/index.ts: Top-level router.
• tools/[domain]/index.ts: Domain-specific router.
• tools/[domain]/[toolName].ts: Individual tool implementation.
• tools/utils/: Cross-cutting workflow utilities.

To recreate the visual structure of professional planning documents (e.g., shaded headers, specific column widths), use the presentation control tools.

Available Styling Tools:

• updateTableCellStyle: Sets cell background, alignment, or text styles.
• updateTableBorders: Modifies border styles.
• updateTableColumnWidth: Adjusts the width of specific columns.
• updateTableRowStyle: Modifies row height or background.

Common Use Cases:

• Shading a header row (e.g., blue background).
• Setting a narrow width for a No. column.
• Setting a wide width for a メモ / 相談 (Memo/Consultation) column.

To use this MCP server, you must first set up credentials in the Google Cloud Console:

1. Go to the Google Cloud Console.
2. Create or select a project.
3. Enable the following APIs: Google Docs API, Google Sheets API, Google Drive API, Gmail API, and Google Calendar API.
4. Configure the OAuth consent screen:
   • Set user type to External.
   • Add your email as a test user.
   • Add the following scopes: gmail.modify, calendar.events, and the standard Docs/Sheets/Drive scopes.
5. Create an OAuth client ID using the Desktop app type.
6. Save the Client ID and Client Secret provided.

The repository includes an opt-in live integration test for cloneTable against the real Google Docs API. This test creates temporary source/target Google Docs, verifies the functionality, and then deletes them.

Requirements:

• Valid GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
• An authorized token stored via npx -y @a-bonus/google-docs-mcp auth.

Command:

GOOGLE_DOCS_LIVE_TESTS=1 npm run test:live:docs