🔧 MCP Google Tools Server

A full-featured Model Context Protocol server for Google Workspace.
Give your AI assistant real-time access to Drive, Gmail, Calendar, Sheets, Docs, and Apps Script.

English docs · Документация на русском

✨ What it can do

Service	Capabilities
📁 Google Drive	Search, copy, move, share, manage permissions
📊 Google Sheets	Read/write ranges, named ranges, filter views, find & replace, CSV export
📄 Google Docs	Read, create, append text, fill templates, export to PDF
📧 Gmail	Draft, send, search, archive, label, delete with confirmation
📅 Google Calendar	List events, find free slots, create meetings with attendees
⚙️ Apps Script	Read, staged updates, auto-backup, rollback
🔗 Resources	Attach live Drive / Gmail / Calendar / Sheets / Docs snapshots to AI context
💬 Prompts	Ready-made AI templates: summarize inbox, analyze spreadsheet, plan week, search files

🧩 MCP Primitives

This server exposes all three MCP primitive types:

🛠 Tools

50+ executable actions
Called by the AI on demand.
Every tool is annotated with
readOnlyHint / destructiveHint
so clients can warn before risky actions.

📦 Resources

Read-only data snapshots
Attach live Google data directly
to the AI context window
without calling a tool.
Supports static URIs and templates.

💬 Prompts

Reusable AI templates
Select a prompt in your MCP client
to fetch live data and start
a structured conversation
in one click.

🚀 Quick Start

1 — Install dependencies

hljs language-bash

pip install -r requirements.txt

2 — Set up Google OAuth

Create an OAuth 2.0 Client ID in Google Cloud Console, download the JSON, and note its path.

Full step-by-step guide: docs/AUTH_SETUP.md · docs/ru/AUTH_SETUP.md

3 — Configure the server

hljs language-bash

cp config.example.yaml config.yaml
# then edit config.yaml — set paths and choose MCP_AUTH_TOKEN

💡 How to create MCP_AUTH_TOKEN

MCP_AUTH_TOKEN is a secret string you choose. You can think of it as a local activation key for this MCP server, not as a network security layer or authentication mechanism.

The server only checks that this token is configured before it starts handling tools — this is an extra safety step to avoid accidental runs without explicit setup.
Invent any random string, e.g. MySecretToken_2026! or use a password generator.
Recommended length: 16+ characters. Avoid reusing passwords.
Set it in config.yaml → mcp_auth_token: "your_token" or as the env var MCP_AUTH_TOKEN.

The token is never sent anywhere — it is only checked locally inside the server process. It does not restrict what your AI agent can do once the server is running. For more details, see docs/SECURITY.md / docs/ru/SECURITY.md.

4 — Connect your IDE

Replace <PROJECT_PATH> with the absolute path to this repository and your_token_here with your token.

Cursor — .cursor/mcp.json or ~/.cursor/mcp.json

hljs language-json

{
  "mcpServers": {
    "google-tools": {
      "command": "python",
      "args": ["<PROJECT_PATH>\\server.py"],
      "env": {
        "MCP_AUTH_TOKEN": "your_token_here",
        "MCP_CONFIG_FILE": "<PROJECT_PATH>\\config.yaml"
      }
    }
  }
}

Windsurf — %APPDATA%\Codeium\Windsurf\mcp_config.json (Windows)

hljs language-json

{
  "mcpServers": {
    "google-tools": {
      "command": "python",
      "args": ["<PROJECT_PATH>\\server.py"],
      "env": {
        "MCP_AUTH_TOKEN": "your_token_here",
        "MCP_CONFIG_FILE": "<PROJECT_PATH>\\config.yaml"
      }
    }
  }
}

VS Code (Copilot MCP) — .vscode/mcp.json or MCP: Open User Configuration

Uses servers (not mcpServers). Requires VS Code 1.102+ and Copilot enabled.

hljs language-json

{
  "servers": {
    "google-tools": {
      "type": "stdio",
      "command": "python",
      "args": ["<PROJECT_PATH>\\server.py"],
      "env": {
        "MCP_AUTH_TOKEN": "your_token_here",
        "MCP_CONFIG_FILE": "<PROJECT_PATH>\\config.yaml"
      }
    }
  }
}

Other IDEs — generic MCP stdio config

Use the same command / args / env. The root key may be mcpServers or servers.

hljs language-json

{
  "mcpServers": {
    "google-tools": {
      "command": "python",
      "args": ["<PROJECT_PATH>\\server.py"],
      "env": {
        "MCP_AUTH_TOKEN": "your_token_here",
        "MCP_CONFIG_FILE": "<PROJECT_PATH>\\config.yaml"
      }
    }
  }
}

5 — Smoke check

After connecting, call get_gmail_profile() in your AI client.
It should return the authenticated Gmail address if OAuth is configured correctly.

📖 Usage Examples

Basic operations

hljs language-yaml

# Verify authentication
Tool: get_gmail_profile
→ Authenticated Gmail address: user@example.com

# Search for files in Drive
Tool: find_files
Arguments: {"query": "name contains 'budget'"}
→ - Budget_2026.xlsx (ID: 1a2b3c...) [spreadsheet]

# Read a Google Sheet
Tool: read_sheet
Arguments: {"spreadsheet_id": "1a2b3c4d5e...", "range_name": "Sheet1!A1:C10"}
→ | Name | Email     | Status |
  | John | j@corp.io | Active |

# Create a draft email (safe by default — never sends without draft_mode=false)
Tool: send_email
Arguments: {"to": "colleague@example.com", "subject": "Notes", "body_text": "...", "draft_mode": true}
→ EMAIL DRAFT CREATED (ID: r1234...) — saved as draft, not sent.

Resources — attach live data to context

hljs language-perl

# Recent Drive files (no arguments needed)
Resource URI: gdrive://recent

# Unread inbox snapshot
Resource URI: gmail://inbox

# This week's calendar
Resource URI: gcalendar://upcoming

# Specific spreadsheet range
Resource URI: gsheets://1a2b3c4d5e.../Sheet1!A1:D20

# Specific Google Doc
Resource URI: gdocs://1a2b3c4d5e...

Prompts — one-click AI workflows

Prompt	What it does
`summarize_inbox`	Fetches recent Gmail messages → ready for AI summary
`analyze_spreadsheet`	Reads a sheet range → ready for AI analysis / charts
`plan_week`	Loads calendar events → ready for scheduling suggestions
`search_drive`	Searches Drive files → ready for organisation advice

🛡 Safety Features

Feature	Tools affected
`confirm=true` required	`delete_email`, `gmail_archive`, `calendar_create_meeting`, `drive_revoke_public`, `doc_fill_template`
`dry_run=true` by default	`batch_delete_emails`, `sheet_find_replace`
Auto dry-run for large ranges	`clear_range` (prompts confirmation above threshold)
Draft mode by default	`send_email` (never sends unless `draft_mode=false`)
Public sharing blocked	`share_file` blocks `type=anyone` unless `allow_public=true`
Tool annotations	Every tool carries `readOnlyHint` / `destructiveHint` for client-side warnings

⚠️ Your AI agent has access to all data you authorize via OAuth. Use read-only scopes for sensitive accounts. See docs/SECURITY.md.

⚙️ Configuration Reference

`config.yaml` keys

Key	Env override	Default	Description
`client_secrets_file`	`GOOGLE_CLIENT_SECRETS_FILE`	—	Path to OAuth JSON downloaded from Google Cloud
`token_file`	`GOOGLE_TOKEN_FILE`	`~/.google/token.json`	Where the OAuth token is saved after first login
`mcp_auth_token`	`MCP_AUTH_TOKEN`	—	Required. Token to activate the server
`log_file`	`GOOGLE_LOG_FILE`	stderr only	Path to a log file (optional)
`log_level`	`GOOGLE_LOG_LEVEL`	`INFO`	Log verbosity: `DEBUG` / `INFO` / `WARNING` / `ERROR`
`backup_dir`	`GOOGLE_BACKUP_DIR`	—	Directory for Apps Script auto-backups
`scopes`	—	full access	List of OAuth scopes (see security docs)

MCP_CONFIG_FILE — points to your config.yaml. Set this in the IDE env block.
Environment variables always override config file values.

Minimal config.yaml example

hljs language-yaml

client_secrets_file: "C:\\Users\\you\\.google\\oauth.keys.json"
token_file: "C:\\Users\\you\\.google\\token.json"
mcp_auth_token: "MySecretToken_2026!"
log_level: "INFO"

📦 Full Tool List

📁 Drive (8 tools)

Tool	Type	Description
`find_files`	read	Search by name or Drive query
`drive_search_advanced`	read	Full Drive query syntax with result limit
`drive_list_permissions`	read	List file permissions
`create_folder`	write	Create a folder
`move_file`	write	Move a file to a folder
`drive_copy_file`	write	Copy a file
`share_file`	write	Share with user/group/domain/anyone
`drive_revoke_public`	destructive	Revoke public access (`confirm=true`)

📊 Sheets (11 tools)

Tool	Type	Description
`read_sheet`	read	Read a cell range
`get_spreadsheet_meta`	read	Spreadsheet metadata
`sheet_export_csv`	read	Export range to CSV
`append_row`	write	Append a row
`update_sheet`	write	Write rows to a range
`create_spreadsheet`	write	Create a new spreadsheet
`add_sheet`	write	Add a new tab/sheet
`sheet_create_filter_view`	write	Create a filter view
`sheet_create_named_range`	write	Create a named range
`sheet_find_replace`	write	Find & replace (`dry_run=true` by default)
`clear_range`	destructive	Clear a range (auto dry-run for large ranges)

📄 Docs (5 tools)

Tool	Type	Description
`read_doc`	read	Read document text
`doc_export_pdf`	read	Export document as binary PDF
`create_doc`	write	Create a new document
`append_to_doc`	write	Append text
`doc_fill_template`	destructive	Fill template placeholders (`confirm=true`)

📧 Gmail (11 tools)

Tool	Type	Description
`get_gmail_profile`	read	Get authenticated email address
`list_emails`	read	List emails (with optional search query)
`read_email`	read	Read a single email
`gmail_search_and_summarize`	read	Search and return brief summary
`create_draft`	write	Create a draft
`send_email`	write	Send or draft an email (`draft_mode=true` by default)
`send_draft`	write	Send an existing draft
`gmail_label_apply`	write	Apply a label (`dry_run=true` by default)
`gmail_archive`	write	Archive a message (`confirm=true`)
`delete_email`	destructive	Delete an email (`confirm=true`)
`batch_delete_emails`	destructive	Delete multiple emails (`dry_run=true` by default)

📅 Calendar (4 tools)

Tool	Type	Description
`list_events`	read	List upcoming events
`calendar_find_free_slots`	read	Find free time slots
`create_event`	write	Create an event
`calendar_create_meeting`	write	Create meeting with attendees (`confirm=true`)

⚙️ Apps Script (6 tools)

Tool	Type	Description
`get_script_content`	read	Read project files
`create_script_project`	write	Create a new project
`prepare_script_update`	write	Stage an update, get `operation_id`
`execute_operation`	write	Execute a staged update (with auto-backup)
`cancel_operation`	write	Cancel a pending staged update
`restore_script_backup`	write	Restore from auto-backup

📚 Documentation

🇬🇧 English

Document	Description
AUTH_SETUP.md	Step-by-step Google OAuth setup guide
TOOLS_REFERENCE.md	Full tools, resources, and prompts reference
SECURITY.md	OAuth scopes, safety features, best practices
IDE_SETUP.md	Cursor, Windsurf, VS Code, and other IDE setup
LEARN.md	How this MCP server was built (step-by-step tutorial)

🇷🇺 На русском

Документ	Описание
AUTH_SETUP.md	Пошаговая настройка Google OAuth
TOOLS_REFERENCE.md	Полный справочник инструментов, ресурсов и промптов
SECURITY.md	OAuth scopes, защиты, рекомендации
IDE_SETUP.md	Настройка Cursor, Windsurf, VS Code и других IDE

⚠️ Responsibility notice

You are responsible for understanding the risks and consequences of operations performed by this server.
Use it at your own discretion and follow your organization's security policies.

Built with ❤️ using Model Context Protocol · MCP Python SDK

yet-another-google-mcp

🔧 MCP Google Tools Server

✨ What it can do

🧩 MCP Primitives

🛠 Tools

📦 Resources

💬 Prompts

🚀 Quick Start

1 — Install dependencies

2 — Set up Google OAuth

3 — Configure the server

4 — Connect your IDE

5 — Smoke check

📖 Usage Examples

🛡 Safety Features

⚙️ Configuration Reference

`config.yaml` keys

📦 Full Tool List

📚 Documentation

🇬🇧 English

🇷🇺 На русском

⚠️ Responsibility notice

Similar Packages

Repository

Original Author

Publisher

yet-another-google-mcp

🔧 MCP Google Tools Server

✨ What it can do

🧩 MCP Primitives

🛠 Tools

📦 Resources

💬 Prompts

🚀 Quick Start

1 — Install dependencies

2 — Set up Google OAuth

3 — Configure the server

4 — Connect your IDE

5 — Smoke check

📖 Usage Examples

🛡 Safety Features

⚙️ Configuration Reference

config.yaml keys

📦 Full Tool List

📚 Documentation

🇬🇧 English

🇷🇺 На русском

⚠️ Responsibility notice

Similar Packages

Repository

Original Author

Publisher

`config.yaml` keys