strands-google
🌐 Google API integration for Strands Agents
Access 200+ Google APIs (Gmail, Drive, Calendar, YouTube, etc.) directly from your Strands agent with simple, powerful tools.
🔌 Use as an MCP server
Use strands-google from Claude Code, Claude Desktop, Cursor, Kiro, or any MCP client — all Google tools (use_google, google_auth, gmail_send, gmail_reply) become MCP tools.
claude mcp add google -- uvx strands-google
Claude Desktop config:
{
"mcpServers": {
"google": {
"command": "uvx",
"args": ["strands-google"]
}
}
}
Options:
strands-google --tools use_google # expose a subset
strands-google --skip gmail # drop a group
strands-google --http --port 8000 # HTTP mode, multi-client
Features
- ✅ Universal Google API Access - Gmail, Drive, Calendar, YouTube, Sheets, Docs, and 200+ more
- 🔐 Flexible Authentication - OAuth 2.0, Service Accounts, and API Keys
- 📧 Gmail Helpers - Easy email sending and replying with automatic encoding
- 🎯 Dynamic Scopes - Configure OAuth scopes on-the-fly
Installation
pip install strands-google
Quick Start
1. Authentication Setup
OAuth 2.0 (Recommended for Gmail/Drive/Calendar)
python -m strands_google.google_auth
This will:
- Open your browser for Google sign-in
- Generate
gmail_token.jsonwith your credentials - Grant access to selected Google APIs
Set the environment variable:
export GOOGLE_OAUTH_CREDENTIALS=~/gmail_token.json
Service Account (For GCP services)
export GOOGLE_APPLICATION_CREDENTIALS=~/service-account-key.json
API Key (For public APIs)
export GOOGLE_API_KEY=your_api_key_here
2. Use with Strands Agents
from strands import Agent
from strands_google import use_google, gmail_send, gmail_reply
agent = Agent(tools=[use_google, gmail_send, gmail_reply])
# Send an email
agent("Send an email to friend@example.com saying hello")
# Search Gmail
agent("Find all unread emails from last week")
# List Google Drive files
agent("Show me my recent Drive files")
Available Tools
use_google - Universal Google API Access
Access any Google API operation:
# Gmail: List messages
agent.tool.use_google(
service="gmail",
version="v1",
resource="users.messages",
method="list",
parameters={"userId": "me", "maxResults": 10}
)
# Drive: List files
agent.tool.use_google(
service="drive",
version="v3",
resource="files",
method="list",
parameters={"pageSize": 10}
)
# Calendar: List events
agent.tool.use_google(
service="calendar",
version="v3",
resource="events",
method="list",
parameters={"calendarId": "primary"}
)
# YouTube: Search videos
agent.tool.use_google(
service="youtube",
version="v3",
resource="search",
method="list",
parameters={"part": "snippet", "q": "python", "maxResults": 5},
credential_type="api_key"
)
gmail_send - Easy Email Sending
Send emails without dealing with base64 encoding:
# Simple email
agent.tool.gmail_send(
to="friend@example.com",
subject="Hello!",
body="This is a test email."
)
# With CC/BCC
agent.tool.gmail_send(
to="friend@example.com",
subject="Team Update",
body="Meeting at 3pm",
cc=["boss@example.com"],
bcc=["archive@example.com"]
)
# HTML email
agent.tool.gmail_send(
to="friend@example.com",
subject="Newsletter",
body="<h1>Hello!</h1><p>This is <b>HTML</b> content.</p>",
html=True
)
gmail_reply - Reply to Emails
Reply to existing messages automatically:
agent.tool.gmail_reply(
message_id="19b1ff0cf255af0d",
body="Thanks! I'll get back to you soon."
)
google_auth - OAuth Authentication Tool
Authenticate and generate OAuth tokens with custom scopes:
from strands_google import google_auth
# Authenticate with default scopes
google_auth(
credentials_file="gmail_credentials.json",
token_file="gmail_token.json"
)
# Authenticate with custom scopes
google_auth(
credentials_file="gmail_credentials.json",
token_file="gmail_token.json",
scopes=[
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/drive.readonly"
]
)
Advanced Usage
Custom OAuth Scopes
Pass custom scopes for specific API access:
agent.tool.use_google(
service="gmail",
version="v1",
resource="users.messages",
method="list",
parameters={"userId": "me"},
scopes=[
"https://www.googleapis.com/auth/gmail.readonly"
]
)
Force Credential Type
Override auto-detection:
# Force OAuth even if service account is set
agent.tool.use_google(
service="gmail",
version="v1",
resource="users.messages",
method="list",
parameters={"userId": "me"},
credential_type="oauth"
)
# Force API key for public APIs
agent.tool.use_google(
service="youtube",
version="v3",
resource="search",
method="list",
parameters={"part": "snippet", "q": "ai"},
credential_type="api_key"
)
Custom HTTP Headers
Some APIs require custom headers:
# Places API with field mask
agent.tool.use_google(
service="places",
version="v1",
resource="places",
method="searchText",
parameters={"body": {"textQuery": "restaurants in NYC"}},
headers={"X-Goog-FieldMask": "places.displayName,places.formattedAddress"}
)
Environment Variables
| Variable | Description | Example |
|---|---|---|
GOOGLE_OAUTH_CREDENTIALS |
Path to OAuth token JSON | ~/gmail_token.json |
GOOGLE_APPLICATION_CREDENTIALS |
Path to service account JSON | ~/service-key.json |
GOOGLE_API_KEY |
API key for public APIs | AIzaSy... |
GOOGLE_API_SCOPES |
Default OAuth scopes (comma-separated) | gmail.readonly,drive.file |
BYPASS_TOOL_CONSENT |
Skip confirmation prompts | true |
Supported Google APIs
This package supports ALL Google APIs via the Discovery API, including:
- 📧 Gmail - Email operations
- 📁 Drive - File storage and management
- 📅 Calendar - Event scheduling
- 📺 YouTube - Video operations
- 📊 Sheets - Spreadsheet operations
- 📝 Docs - Document operations
- 🎨 Slides - Presentation operations
- 📸 Photos - Photo library management
- ✅ Tasks - Task management
- 👥 Contacts - Contact management
- ☁️ Cloud Platform - GCP services
- 📊 Analytics - Web analytics
- 🎓 Classroom - Education platform
- 📝 Forms - Form responses
- 🗺️ Maps/Places - Location services
- And 180+ more!
Security & Safety
- Confirmation Prompts: Mutative operations (create, delete, modify) require confirmation
- Bypass Option: Set
BYPASS_TOOL_CONSENT=trueto skip prompts (be careful!) - Dynamic Scopes: Only request the permissions you need
- Credential Isolation: Separate OAuth and service account credentials
Development
# Clone the repo
git clone https://github.com/cagataycali/strands-google
cd strands-google
# Install in development mode
pip install -e .
# Run authentication helper
python -m strands_google.google_auth
Troubleshooting
"Permission denied" errors
Your OAuth token doesn't have the required scope. Re-authenticate with broader scopes:
python -m strands_google.google_auth
"Quota exceeded" errors
You've hit API rate limits. Wait a few minutes and try again, or check your quota in Google Cloud Console.
"Credentials not found" errors
Ensure you've set the appropriate environment variable:
GOOGLE_OAUTH_CREDENTIALSfor OAuthGOOGLE_APPLICATION_CREDENTIALSfor service accountsGOOGLE_API_KEYfor API keys
Contributing
Contributions welcome! Please open an issue or PR on GitHub.
License
Apache 2 License - see LICENSE file for details
Links
Built with ❤️ for the Strands Agents community
Metadata
Release files for strands-google 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| strands_google-0.2.0.tar.gz | 21.4 kB | Without provenance | Details for strands_google-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| strands_google-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for strands_google-0.2.0-py3-none-any.whl |
Total release size: 44.3 kB
Release files / strands_google-0.2.0.tar.gz
| Download URL | strands_google-0.2.0.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2735848212825224a87046854455a03ac64ff48ac472982daa65ad4d7817bc96
|
|
BLAKE2b-256 checksum How to use checksums |
e19f5bf03aa17f287d7d3331d45a4145728870a263547ac8cdaab36b3bade370
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Release files / strands_google-0.2.0-py3-none-any.whl
| Download URL | strands_google-0.2.0-py3-none-any.whl |
|---|---|
| Size | 22.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1043736aa271be635af21536c4498ed44b93f6b3d9de8100d4951d7a9340825a
|
|
BLAKE2b-256 checksum How to use checksums |
13b1d5642c0c33418b52e586d837ddfc8addaa364cec1d174d9e5c456d535353
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Security for strands-google 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.