google-docs

An AI agent skill for interacting with Google Docs - create documents, search by title, read content, and edit text. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the Agent Skills Standard.

Features

• Create Documents - Create new Google Docs with optional content
• Search - Find documents by title
• Read Content - Extract text from documents
• Edit - Append, insert, or replace text

Lightweight alternative to the full Google Workspace MCP server.

⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.

Quick Start

1. Install dependencies

pip install keyring

2. Authenticate

python scripts/auth.py login

This opens a browser for Google OAuth. Tokens are stored securely in your system keyring.

3. Test connection

python scripts/auth.py status

Usage Examples

# Create a new document
python scripts/docs.py create "Meeting Notes"

# Create with initial content
python scripts/docs.py create "Project Plan" --content "# Overview\n\nThis is the plan."

# Find documents by title
python scripts/docs.py find "meeting" --limit 10

# Get text content of a document
python scripts/docs.py get-text 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

# Get text using a full URL
python scripts/docs.py get-text "https://docs.google.com/document/d/1BxiMVs.../edit"

# Append text to end of document
python scripts/docs.py append-text DOC_ID "New paragraph at the end."

# Insert text at beginning
python scripts/docs.py insert-text DOC_ID "Text at the beginning.\n\n"

# Replace text in document
python scripts/docs.py replace-text DOC_ID "old text" "new text"

Command Reference

| Command | Description | Arguments | |---------|-------------|-----------| | create <title> | Create new document | title, --content | | find <query> | Search by title | search query, --limit | | get-text <id> | Get document text | document ID or URL | | append-text <id> <text> | Append to end | document ID, text | | insert-text <id> <text> | Insert at start | document ID, text | | replace-text <id> <old> <new> | Replace text | document ID, old, new |

Document ID Format

Google Docs uses IDs like 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms. You can:

• Use the full URL (ID is extracted automatically)
• Use just the document ID
• Get document IDs from the find command

Token Management

Tokens stored securely using the system keyring:

• macOS: Keychain
• Windows: Windows Credential Locker
• Linux: Secret Service API (GNOME Keyring, KDE Wallet)

Service name: google-docs-skill-oauth

Troubleshooting

"Failed to get access token"

Run python scripts/auth.py login to authenticate.

"Document not found"

Check that the document ID is correct and you have access to the document.

"Permission denied"

You need edit access to modify a document. Check sharing settings.

License

Apache 2.0