tonytcampbell/my_mcp_servers

Google Docs MCP Server

A comprehensive Model Context Protocol (MCP) server implementation for Google Documents integration. This server provides AI assistants with the ability to create, read, and update Google Docs with support for complex content including tables, charts, smart chips, and rich text formatting.

Features

✅ Document Creation - Create new Google Documents with titles and initial content
✅ Document Reading - Read existing documents with multiple output formats (JSON, Markdown, Plain Text)
✅ Document Updates - Update existing documents with text insertion, replacement, and table creation
✅ Complex Content Support - Handle tables, charts, and smart chips
✅ Rich Text Formatting - Support for bold, italic, headers, lists, and more
✅ Multi-tab Documents - Navigate and process documents with multiple tabs
✅ Drive Integration - Move documents to specific folders
✅ URL Support - Work with both Google Docs URLs and document IDs

Architecture

This implementation follows the specification outlined in llm_generated.md and provides:

• GoogleDocsService: Core service class handling Google API operations
• MCP Protocol Compliance: Full implementation of MCP server interface
• OAuth 2.0 Authentication: Secure authentication with automatic token refresh
• Error Handling: Comprehensive error handling with logging
• Type Safety: Full type hints for better development experience

Quick Start

1. Installation

# Clone or download the project files
git clone <repository-url>
cd google-docs-mcp

# Install dependencies
pip install -r requirements.txt

2. Google Cloud Setup

Follow the detailed to:

• Create a Google Cloud project
• Enable required APIs (Google Docs API, Google Drive API)
• Configure OAuth consent screen
• Download credentials file

3. Run the Server

python google_docs_mcp_server.py

On first run, you'll be prompted to authenticate with Google in your browser.

Available Tools

create_google_document

Create a new Google Document with optional initial content.

Parameters:

• title (required): Document title
• content (optional): Initial content text
• folder_id (optional): Google Drive folder ID

Example:

{
  "title": "Meeting Notes - Q4 Planning",
  "content": "# Q4 Planning Meeting\n\nDate: Today\nAttendees: Team leads",
  "folder_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
}

read_google_document

Read content from an existing Google Document.

Parameters:

• document_url_or_id (required): Google Docs URL or document ID
• include_tabs (optional): Include all document tabs (default: true)
• format (optional): Output format - "json", "markdown", or "plain_text"

Example:

{
  "document_url_or_id": "https://docs.google.com/document/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit",
  "format": "markdown"
}

update_google_document

Update content in an existing Google Document.

Parameters:

• document_id (required): Google Document ID
• content_updates (required): Array of update operations
• tab_id (optional): Specific tab to update
• preserve_formatting (optional): Preserve existing formatting

Update Operations:

• insert_text: Insert text at a specific index
• replace_text: Replace text in a range
• insert_table: Insert a table with specified dimensions

Example:

{
  "document_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "content_updates": [
    {
      "action": "insert_text",
      "text": "Updated on: 2024-01-15\n",
      "index": 1
    },
    {
      "action": "insert_table",
      "rows": 3,
      "columns": 2,
      "index": 50
    }
  ]
}

Content Handling

Rich Text Formatting

The server preserves and converts rich text formatting:

• Bold and italic text
• Headers (H1, H2, H3)
• Bulleted and numbered lists
• Font styles and colors

Tables

Full table support including:

• Reading table structure and content
• Creating new tables with specified dimensions
• Extracting table data to various formats
• Converting tables to Markdown

Multi-format Output

Documents can be output in multiple formats:

• JSON: Structured data with formatting information
• Markdown: Clean markdown with preserved formatting
• Plain Text: Simple text extraction

Integration Examples

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-docs": {
      "command": "python",
      "args": ["/path/to/google_docs_mcp_server.py"],
      "cwd": "/path/to/project"
    }
  }
}

Usage with AI Assistants

Example prompts you can use with the server:

"Create a new document called 'Project Proposal' with a basic outline"

"Read the content from this Google Doc: [URL] and convert it to markdown"

"Update my meeting notes document by adding today's action items at the end"

"Extract all the tables from this document and format them as markdown"

Error Handling

The server includes comprehensive error handling for:

• Authentication failures
• Invalid document IDs or URLs
• API rate limiting
• Network connectivity issues
• Malformed content updates

All errors are logged and returned with descriptive messages.

Security and Privacy

• OAuth 2.0: Secure authentication with automatic token refresh
• Local Storage: Credentials stored locally, never transmitted
• Minimal Permissions: Requests only necessary Google API scopes
• Audit Trail: All operations logged for debugging

API Limits

Be aware of Google API quotas:

• Google Docs API: 100 requests per 100 seconds per user
• Google Drive API: 1,000 requests per 100 seconds per user

The server includes automatic retry logic with exponential backoff for rate limiting.

Development

Project Structure

google-docs-mcp/
├── google_docs_mcp_server.py    # Main server implementation
├── requirements.txt             # Python dependencies
├── setup_guide.md              # Detailed setup instructions
├── llm_generated.md            # Original specification
├── credentials.json            # Google OAuth credentials (not committed)
└── token.json                  # Saved authentication token (not committed)

Contributing

1. Follow the existing code style and type hints
2. Add comprehensive error handling
3. Include docstrings for all functions
4. Test with various document types and formats
5. Update documentation for new features

Testing

Test the server with various scenarios:

• Documents with different content types
• Large documents with many elements
• Documents with complex formatting
• Multi-tab documents
• Error conditions (invalid IDs, network issues)

Troubleshooting

See the for detailed troubleshooting steps.

Common issues:

• Authentication errors: Check Google Cloud Console setup
• Permission denied: Verify OAuth consent screen configuration
• Rate limiting: Implement proper retry logic and request throttling

License

This implementation is provided as-is for educational and development purposes. Please ensure compliance with Google's API Terms of Service and your organization's security policies.

Related Documentation

• - Detailed technical specification
• - Complete setup instructions
• Google Docs API Documentation
• Model Context Protocol Specification