Google Search Console MCP Python
No description available
Ask AI about Google Search Console MCP Python
Powered by Claude · Grounded in docs
I know everything about Google Search Console MCP Python. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Google Search Console MCP Server
A Model Context Protocol (MCP) server for comprehensive Google Search Console API access, built with FastMCP.
Features
- Search Analytics - Query performance data with clicks, impressions, CTR, and position metrics
- Site Management - List, add, remove, and inspect Search Console properties
- URL Inspection - Check index status and crawl information for specific URLs
- Domain Delegation - Support for service account impersonation across Google Workspace domains
- FastMCP Framework - Built with the fast, Pythonic way to create MCP servers
- Type Safety - Full type hints and Pydantic validation
- Comprehensive Logging - Structured logging with loguru
Installation
Using uv (Recommended)
# Install globally
uv tool install google-search-console-mcp-python
# Run directly without installation
uvx google-search-console-mcp-python
Using pip
pip install google-search-console-mcp-python
Authentication Setup
Service Account Creation
- Go to Google Cloud Console
- Create/select project and enable "Search Console API"
- Create Service Account with JSON key
- In Search Console, add service account email as property owner
Domain-Wide Delegation (Optional)
For Google Workspace domains to impersonate users:
- Enable domain-wide delegation in service account settings
- In Google Admin Console, authorize the service account
- Add required scopes:
https://www.googleapis.com/auth/webmastershttps://www.googleapis.com/auth/webmasters.readonly
Configuration
Environment Variables
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
export GOOGLE_APPLICATION_SUBJECT=admin@yourdomain.com # Optional: for domain delegation
Running the Server
# Using uvx (recommended)
uvx google-search-console-mcp-python
# With domain delegation
GOOGLE_APPLICATION_SUBJECT=admin@domain.com uvx google-search-console-mcp-python
# Using pip installation
google-search-console-mcp-python
Claude Desktop Configuration
{
"mcpServers": {
"gsc": {
"command": "uvx",
"args": ["google-search-console-mcp-python"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json",
"GOOGLE_APPLICATION_SUBJECT": "admin@domain.com"
}
}
}
}
Available Tools
search_analytics
Retrieve search performance data with comprehensive metrics and dimensions.
Parameters:
site_url(required): Property URLstart_date,end_date(required): Date range (YYYY-MM-DD)dimensions: Array of dimension strings:["query", "page", "country", "device", "searchAppearance"]search_type: One of:"web","image","video","news","discover","googleNews"aggregation_type: One of:"auto","byPage","byProperty","byNewsShowcasePanel"row_limit: Max 25,000 rows (default: 1,000)
Example:
{
"site_url": "https://example.com",
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"dimensions": ["query", "country"],
"search_type": "web",
"row_limit": 5000
}
list_sites
List all Search Console properties accessible to the authenticated account.
get_site
Get detailed information about a specific Search Console property.
Parameters:
site_url(required): Property URL
add_site
Add a new property to Search Console.
Parameters:
site_url(required): Property URL to add
delete_site
Remove a property from Search Console.
Parameters:
site_url(required): Property URL to remove
inspect_url
Inspect URL index status and crawl information.
Parameters:
site_url(required): Property containing the URLinspection_url(required): URL to inspectlanguage_code(optional): Language code (e.g., 'en-US')
Development
Setup Development Environment
# Clone the repository
git clone https://github.com/locomotive-agency/google-search-console-mcp-python.git
cd google-search-console-mcp-python
# Install dependencies
uv sync
# Install pre-commit hooks
uv run pre-commit install
Code Quality
# Format code
uv run ruff format
# Lint code
uv run ruff check
# Type checking
uv run mypy src/
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src
Testing
# Run all tests
uv run pytest
# Run specific test file
uv run pytest tests/test_server.py -v
# Run with coverage report
uv run pytest --cov=src --cov-report=html
Requirements
- Python 3.12+
- Google Cloud project with Search Console API enabled
- Service account with Search Console access
- uv package manager (recommended)
Architecture
Built with modern Python best practices:
- FastMCP - High-performance MCP server framework
- Pydantic - Type validation and settings management
- Loguru - Structured logging
- Google API Client - Official Google APIs library
- Async/Await - Non-blocking I/O operations
Publishing
# Build the package
uv build
# Publish to PyPI (requires authentication)
uv publish
Contributing
- Fork the repository
- Create a feature branch
- Make your changes following code quality standards
- Add tests for new functionality
- Submit a pull request
License
MIT
Built with ❤️ by Locomotive Agency using the FastMCP framework.
Inspired by and adapted from guchey/mcp-server-google-search-console.
