# gsc-mcp

[![npm version](https://img.shields.io/npm/v/@mikusnuz%2Fgsc-mcp)](https://www.npmjs.com/package/@mikusnuz/gsc-mcp)

[English](README.md) | [한국어](README.ko.md)

[![MCP Badge](https://lobehub.com/badge/mcp/mikusnuz-gsc-mcp)](https://lobehub.com/mcp/mikusnuz-gsc-mcp)

MCP server for **Google Search Console API** and **Google Indexing API** — full API coverage.

Requires Node.js 20 or newer, matching the MCP SDK's installed runtime dependencies.

## When to Use

| Task | Tool |
|------|------|
| "Check which queries my site ranks for" | `search_analytics_query` |
| "Notify Google about an eligible job posting or livestream URL" | `indexing_publish` |
| "Find pages with indexing errors" | `url_inspection_inspect` |
| "Get search performance data for the last 30 days" | `search_analytics_query` |
| "Compare click-through rates between mobile and desktop" | `search_analytics_query` (group by `device`) |
| "Submit my sitemap to Google" | `sitemaps_submit` |
| "Batch notify eligible job posting/livestream URLs" | `indexing_batch_publish` |

> **For AI agents:** See [`llms.txt`](llms.txt) for a machine-readable summary. Copy [`templates/CLAUDE.md`](templates/CLAUDE.md) or [`templates/AGENTS.md`](templates/AGENTS.md) into your project to teach your agent about this MCP.

Unlike other GSC MCP servers that only wrap `searchAnalytics.query`, this server exposes **every endpoint** available in the Google Search Console and Indexing APIs.

## Tools (13)

### Sites
| Tool | Description |
|------|-------------|
| `sites_list` | List all sites (properties) in your Search Console |
| `sites_get` | Get details of a specific site |
| `sites_add` | Add a new site (property) |
| `sites_delete` | Remove a site |

### Sitemaps
| Tool | Description |
|------|-------------|
| `sitemaps_list` | List all submitted sitemaps for a site |
| `sitemaps_get` | Get details of a specific sitemap |
| `sitemaps_submit` | Submit a sitemap |
| `sitemaps_delete` | Delete a sitemap |

### Search Analytics
| Tool | Description |
|------|-------------|
| `search_analytics_query` | Query search performance data (clicks, impressions, CTR, position) with filtering and grouping. Supports hourly data with the `hour` dimension. |

### URL Inspection
| Tool | Description |
|------|-------------|
| `url_inspection_inspect` | Inspect a URL's index status, crawl info, rich results, and AMP (the deprecated mobile-usability field may be absent) |

### Indexing API
| Tool | Description |
|------|-------------|
| `indexing_publish` | Notify Google about an eligible `JobPosting` or `BroadcastEvent` URL update/removal |
| `indexing_get_metadata` | Get latest notification metadata for an eligible URL (requires `contentType`; not index status) |
| `indexing_batch_publish` | Batch notify up to 100 eligible URLs and report every embedded request status |

> **Indexing API eligibility:** Google supports this API only for pages with
> `JobPosting` structured data or livestream pages with `BroadcastEvent`
> embedded in a `VideoObject`. The tools require `contentType` so callers must
> identify which supported type applies. A successful API response confirms
> receipt of the notification; it does not guarantee that Google indexed the
> URL. Use `url_inspection_inspect` to check index status. See Google's
> [Indexing API usage guide](https://developers.google.com/search/apis/indexing-api/v3/using-api).

### Indexing API quotas

Google's default per-project limits are 200 publish requests per day, 180
metadata requests per minute, and 380 requests per minute across endpoints.
The daily limit resets at midnight Pacific Time. A batch of 100 URLs still
consumes 100 requests; batching reduces connections, not quota usage. Check
your project's actual quota before sending notifications. See the official
[quota reference](https://developers.google.com/search/apis/indexing-api/v3/quota-pricing).

## Authentication

Two authentication methods are supported:

### Option 1: OAuth2 Refresh Token

```json
{
  "mcpServers": {
    "gsc-mcp": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/gsc-mcp"],
      "env": {
        "GSC_CLIENT_ID": "your-client-id",
        "GSC_CLIENT_SECRET": "your-client-secret",
        "GSC_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

Required OAuth2 scopes:
- `https://www.googleapis.com/auth/webmasters`
- `https://www.googleapis.com/auth/indexing`

### Option 2: Service Account

```json
{
  "mcpServers": {
    "gsc-mcp": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/gsc-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account-key.json"
      }
    }
  }
}
```

For Search Console read/write tools, add the service account as an owner or user
with sufficient permission. For **Indexing API** tools, Google requires the
service account to be added as a **delegated owner** of the property; user-level
access is not sufficient.

## Setup Guide

### OAuth2 Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project (or select existing)
3. Enable **Search Console API** and **Indexing API**
4. Create OAuth 2.0 credentials (Desktop app type)
5. Use the [OAuth Playground](https://developers.google.com/oauthplayground/) to generate a refresh token with scopes:
   - `https://www.googleapis.com/auth/webmasters`
   - `https://www.googleapis.com/auth/indexing`

### Service Account Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a service account
3. Download the JSON key file
4. Enable **Search Console API** and **Indexing API**
5. In Search Console, add the service account email as an owner for your sites

## License

MIT