README.md•5.05 kB
# Google Search Console MCP Server
[](https://smithery.ai/server/mcp-server-gsc)
A Model Context Protocol (MCP) server providing comprehensive access to Google Search Console data with enhanced analytics capabilities.
### Sponsored by
<a href="https://macuse.app">
<img src="https://macuse.app/logo.png" width="100" alt="Macuse">
</a>
## Features
- **Enhanced Search Analytics**: Retrieve up to 25,000 rows of performance data
- **Advanced Filtering**: Support for regex patterns and multiple filter operators
- **Quick Wins Detection**: Automatically identify optimization opportunities
- **Rich Dimensions**: Query, page, country, device, and search appearance analysis
- **Flexible Date Ranges**: Customizable reporting periods with historical data access
## Prerequisites
- Node.js 18 or later
- Google Cloud Project with Search Console API enabled
- Service Account credentials with Search Console access
## Installation
### Installing via Smithery
To install Google Search Console for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-server-gsc):
```bash
npx -y @smithery/cli install mcp-server-gsc --client claude
```
### Manual Installation
```bash
npm install mcp-server-gsc
```
## Authentication Setup
To obtain Google Search Console API credentials:
1. Visit the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the API:
- Go to "APIs & Services" > "Library"
- Search for and enable ["Search Console API"](https://console.cloud.google.com/marketplace/product/google/searchconsole.googleapis.com)
4. Create credentials:
- Navigate to ["APIs & Services" > "Credentials"](https://console.cloud.google.com/apis/credentials)
- Click "Create Credentials" > "Service Account"
- Fill in the service account details
- Create a new key in JSON format
- The credentials file (.json) will download automatically
5. Grant access:
- Open Search Console
- Add the service account email (format: name@project.iam.gserviceaccount.com) as a property administrator
## Usage
### Claude Desktop Configuration
```json
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["-y", "mcp-server-gsc"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
}
}
}
}
```
## Available Tools
### search_analytics
Get comprehensive search performance data from Google Search Console with enhanced analytics capabilities.
**Required Parameters:**
- `siteUrl`: Site URL (format: `http://www.example.com/` or `sc-domain:example.com`)
- `startDate`: Start date (YYYY-MM-DD)
- `endDate`: End date (YYYY-MM-DD)
**Optional Parameters:**
- `dimensions`: Comma-separated list (`query`, `page`, `country`, `device`, `searchAppearance`, `date`)
- `type`: Search type (`web`, `image`, `video`, `news`, `discover`, `googleNews`)
- `aggregationType`: Aggregation method (`auto`, `byNewsShowcasePanel`, `byProperty`, `byPage`)
- `rowLimit`: Maximum rows to return (default: 1000, max: 25000)
- `dataState`: Data freshness (`all` or `final`, default: `final`)
**Filter Parameters:**
- `pageFilter`: Filter by page URL (supports regex with `regex:` prefix)
- `queryFilter`: Filter by search query (supports regex with `regex:` prefix)
- `countryFilter`: Filter by country ISO 3166-1 alpha-3 code (e.g., `USA`, `CHN`)
- `deviceFilter`: Filter by device type (`DESKTOP`, `MOBILE`, `TABLET`)
- `searchAppearanceFilter`: Filter by search feature (e.g., `AMP_BLUE_LINK`, `AMP_TOP_STORIES`)
- `filterOperator`: Operator for filters (`equals`, `contains`, `notEquals`, `notContains`, `includingRegex`, `excludingRegex`)
**Quick Wins Detection:**
- `detectQuickWins`: Enable automatic detection of optimization opportunities (default: `false`)
- `quickWinsConfig`: Configuration for quick wins detection:
- `positionRange`: Position range to consider (default: `[4, 20]`)
- `minImpressions`: Minimum impressions threshold (default: `100`)
- `minCtr`: Minimum CTR percentage (default: `1`)
**Example - Basic Query:**
```json
{
"siteUrl": "https://example.com",
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"dimensions": "query,page",
"rowLimit": 5000
}
```
**Example - Advanced Filtering with Regex:**
```json
{
"siteUrl": "https://example.com",
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"dimensions": "page,query",
"queryFilter": "regex:(AI|machine learning|ML)",
"filterOperator": "includingRegex",
"deviceFilter": "MOBILE",
"rowLimit": 10000
}
```
**Example - Quick Wins Detection:**
```json
{
"siteUrl": "https://example.com",
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"dimensions": "query,page",
"detectQuickWins": true,
"quickWinsConfig": {
"positionRange": [4, 15],
"minImpressions": 500,
"minCtr": 2
}
}
```
## License
MIT
## Contributing
Contributions are welcome! Please read our contributing guidelines before submitting pull requests.