# Google Search Console MCP: connect your agent to search data

URL: https://serpel.app/blog/google-search-console-mcp

Updated: 2026-10-10

A Google Search Console MCP server lets an AI agent read your clicks, impressions and queries through the Model Context Protocol instead of CSV exports. You can wrap the Search Console API yourself, run a community server or connect a hosted one. This guide walks through the hosted route with Serpel’s MCP server and its `get_search_performance` tool, including what the tool returns and which permissions it needs.

## Key takeaways

- MCP is an open standard for connecting AI applications to external systems. A Search Console MCP server is a tool layer on top of the Search Console API.
- You can build your own wrapper, run a community server with your own Google Cloud credentials, or use a hosted server where you only sign in.
- Serpel’s `get_search_performance` tool returns totals, the previous period and the top queries or pages for the connected property. It is read-only and free to call.
- Keep the Google scope read-only, approve tool calls, treat query text as untrusted, and revoke connected apps you no longer use.

## What is a Google Search Console MCP server?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open-source standard for connecting AI applications to external systems. Its documentation compares it to a USB-C port for AI applications: one standard way to plug in data sources, tools and workflows. An MCP server offers tools. According to the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), each tool has a name, a description and an input schema. The model can discover and call tools on its own, while the application should keep a human able to deny calls.

A Google Search Console MCP server is that tool layer on top of the Search Console API. The API’s [Search Analytics query method](https://developers.google.com/webmaster-tools/v1/searchanalytics/query) returns clicks, impressions, click-through rate and average position, grouped by dimensions such as query, page or date. One request returns at most 25,000 rows, and Google notes that the API does not guarantee to return all data rows. It accepts either the read-only scope `https://www.googleapis.com/auth/webmasters.readonly` or the broader `webmasters` scope.

Instead of exporting a report and pasting it into a chat, the agent calls a tool, gets rows back and reasons over them. That also lets it combine search data with other sources, such as crawl results or your code.

## What are your options for giving an agent Search Console data?

**Ways to connect an AI agent to Search Console**
| Option | Authentication | What you maintain | Watch out for |
| --- | --- | --- | --- |
| Your own wrapper around the Search Console API | OAuth client or service account | A service that exposes the API as MCP tools | You handle quotas, paging and the 25,000-row limit per request |
| Community server [mcp-server-gsc](https://github.com/ahonn/mcp-server-gsc) | Service account JSON key | A Node.js process on your machine. Its README describes one `search_analytics` tool | The service account email must be added to your property, and the key file is a secret |
| Community server [mcp-gsc](https://github.com/AminForou/mcp-gsc) | OAuth desktop client or service account | A Python process. Its README lists around 15 tools, including URL inspection and sitemap management | Some tools can change data. Destructive ones are off unless you enable them |
| Hosted server, such as Serpel’s | Browser sign-in (OAuth) or an API token with scopes | Nothing to host. The Search Console connection lives in your Serpel project | Needs a Serpel account and a connected project |

Neither community project lives in a Google GitHub organisation. Read the code, check how recently it was updated and pin a version before you give any server credentials. The rest of this guide covers the hosted route, because it needs no Google Cloud project.

Choose by what else the agent needs. If it only reads Search Console, a community server with a service account is a small job, provided you are comfortable running and updating it. If the agent also needs crawl results, rankings or your code structure, a hosted server saves you from wiring several sources together. If all data must stay on your own infrastructure, build the wrapper yourself.

## How do you connect Search Console to Claude Code with Serpel’s MCP server?

The server runs at `https://serpel.app/mcp`. You can follow the same steps in Cursor or Codex, using the [Claude Code guide](https://serpel.app/docs/mcp/claude-code) as the model, or read the [MCP overview for developers](https://serpel.app/developers/mcp) first.

1. **Connect Search Console to a project** Open the project’s Search data page and connect Google Search Console, or run the CLI command below. Google asks for read-only access. Serpel selects the property that matches the project’s domain when it can, and you pick one if it can’t. Bing Webmaster Tools works too and connects with an API key.

```bash
serpel search connect-google --project <project-id>
serpel search status --project <project-id>
```

2. **Add the MCP server** Register Serpel as a remote HTTP server in Claude Code.

```bash
claude mcp add --transport http serpel https://serpel.app/mcp
```

3. **Sign in** Run `/mcp` inside Claude Code and follow the browser steps. You approve the access once on Serpel’s consent screen, and per the [Claude Code documentation](https://code.claude.com/docs/en/mcp) the client stores the token securely and refreshes it automatically.

4. **Find your project** Ask the agent to list your Serpel projects. It calls `list_projects` and gets a project ID for each one.

5. **Ask a question** Ask something like “Which landing pages brought the most clicks in the last 28 days?” The agent chooses `get_search_performance` and sends arguments like these.

```json
{
  "projectId": "<project-id>",
  "days": 28,
  "dimension": "page",
  "provider": "google",
  "limit": 25
}
```

## What does the get_search_performance tool return?

The tool is one of 13 on the server and needs a connected Search Console or Bing property. Only `projectId` is required.

**Input of get_search_performance**
| Parameter | Values | Default |
| --- | --- | --- |
| `projectId` | A project ID from `list_projects` | Required |
| `days` | 7, 28, 90 | 28 |
| `dimension` | `query` or `page` | `query` |
| `provider` | `google` (Search Console) or `bing` (Webmaster Tools) | `google` |
| `limit` | 1 to 25 rows | 25 |

A short summary sentence comes first, followed by compact JSON. The data contains the totals, the previous period of the same length, the percentage change in clicks and the top rows sorted by clicks. For queries, a `tracked` flag shows whether the query is already a rank-tracking keyword in the project. Google results use the web search type.

```json
{
  "provider": "google",
  "site": "sc-domain:example.com",
  "period": { "startDate": "2026-09-08", "endDate": "2026-10-05", "days": 28 },
  "totals": { "clicks": 1240, "impressions": 38900, "ctrPercent": 3.19, "averagePosition": 14.8 },
  "previousPeriod": { "clicks": 1165, "impressions": 37200, "ctrPercent": 3.13, "averagePosition": 15.3 },
  "clicksChangePercent": 6.4,
  "dimension": "page",
  "rows": [
    { "page": "https://example.com/pricing", "clicks": 212, "impressions": 4300, "ctrPercent": 4.93, "averagePosition": 6.1, "tracked": false }
  ],
  "truncated": false,
  "cached": false,
  "fetchedAt": "2026-10-07T08:15:00.000Z"
}
```

- **The period ends two days before today.** Search Console data arrives with a delay, and [Google’s guide to retrieving all data](https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data) says it is typically available after two to three days.
- **Results are cached for up to six hours.** The `cached` and `fetchedAt` fields tell the agent when the data was fetched.
- **Without a connection the tool returns an error** that points to the project settings. Nothing is guessed.
- **Reading is free.** The tool is read-only and costs no credits.

## What do the common errors mean?

Tool errors come back as results with an error code and a short message, so the agent can explain the problem or retry.

**Errors you may see from get_search_performance**
| Error code | Meaning | What to do |
| --- | --- | --- |
| `validation_error` | The project has no Search Console or Bing connection with a selected property, or an input is invalid | Connect the property in the project’s search data settings and ask again |
| `forbidden` | The token lacks a scope, or your role in the project is too low | Sign in again with OAuth, or create a token with `mcp:read` and `projects:read` |
| `provider_error` | The data provider is unreachable, or the connection must be reconnected | Reconnect Search Console and retry later |
| `rate_limited` | A provider or workspace limit was reached | Wait for the number of seconds in `retryAfterSeconds`, then retry |
| `not_found` | The project does not exist or you cannot access it | Use an ID returned by `list_projects` |

## Which prompts work well with search data?

Good prompts name a period and a decision. Each one below maps to what the tools actually return.

- “Compare clicks over the last 7 days with the previous 7 days and tell me whether the change looks meaningful.” The agent uses `days: 7` and the change in clicks.
- “List my top landing pages over 90 days and flag any with a click-through rate below the site average.” It compares each row’s `ctrPercent` with the totals.
- “Which of my top queries are not tracked as keywords yet?” It reads the `tracked` flag and can then suggest additions.
- “Show queries between positions 4 and 20 with at least 100 impressions and propose page updates.” This uses `find_keyword_opportunities` with the `minImpressions` input.
- “Which high-traffic pages have crawl errors, and which source files render them?” It chains `get_search_performance`, `get_crawl_issues` and `get_codebase_overview`.

To see how the connection works with search data in the dashboard, read about [Search Console and Bing data in Serpel](https://serpel.app/features/search-data).

## Is it safe to give an AI agent access to Search Console?

It can be, if you control the permissions. These points follow the [MCP security guidance](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) and the [authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).

- **Keep Google access read-only.** Serpel asks Google for the `webmasters.readonly` scope. The tool is also marked read-only, but the MCP specification says clients must treat such annotations as untrusted unless the server is trusted. The read-only Google scope is the real protection.
- **Use tokens bound to the server.** The authorization specification says an MCP server must only accept tokens issued for it. Serpel’s OAuth access tokens work only at the MCP server, and the REST API rejects them.
- **Grant the minimum scopes.** With an API token, `mcp:read` and `projects:read` are enough for this tool. You can also limit a token to single projects. A token for Cursor looks like this:

```json
{
  "mcpServers": {
    "serpel": {
      "url": "https://serpel.app/mcp",
      "headers": { "Authorization": "Bearer ${env:SERPEL_TOKEN}" }
    }
  }
}
```

- **Treat local servers like any program you run.** The MCP security guidance warns that a local server runs with your privileges. Check the exact command before you approve it, and handle a service account key like a password.
- **Treat query text as data, not instructions.** Search queries are typed by strangers. The Claude Code documentation warns that servers which fetch external content can expose you to prompt injection, so keep approval on for tools that can change anything.
- **Revoke what you no longer use.** Connected apps are listed under Settings, API, and disconnecting one revokes its access immediately. The only paid tool, `research_keywords`, runs only if the workspace owner has allowed agents to spend credits.

## Frequently asked questions

### Can an AI agent read my Google Search Console data?

Yes. An agent can call the Search Console API directly through code you write, or through an MCP server that wraps it. Either way, Google decides access through the scope you grant, and the read-only scope is enough for performance data.

### What is the difference between the Search Console API and an MCP server?

The API is a set of HTTP endpoints you code against. An MCP server publishes selected API calls as named tools with input schemas, so any MCP-capable agent can discover and call them without custom integration code.

### Which Google permission does a Search Console MCP server need?

For clicks, impressions, CTR and position, Google’s Search Analytics method accepts the read-only scope `webmasters.readonly` or the broader `webmasters` scope. Choose the read-only one unless a tool needs to change data, such as submitting sitemaps.

### Does get_search_performance cost credits?

No. Reading Search Console data through the tool is free. The only paid MCP tool is `research_keywords`, which books credits and runs only when the workspace owner allows agent spending.

### How fresh is the search data an agent sees?

The period ends two days before today because Search Console data arrives with a delay, and results are cached for up to six hours. The response includes `cached` and `fetchedAt` so an agent can say how current its answer is.

## Sources

- [Model Context Protocol: What is MCP?](https://modelcontextprotocol.io/docs/getting-started/intro), accessed 2026-10-10
- [Model Context Protocol specification: Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), accessed 2026-10-10
- [Model Context Protocol specification: Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), accessed 2026-10-10
- [Model Context Protocol: Security best practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices), accessed 2026-10-10
- [Google Search Console API: Search Analytics query](https://developers.google.com/webmaster-tools/v1/searchanalytics/query), accessed 2026-10-10
- [Google Search Console API: Get all of your data](https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data), accessed 2026-10-10
- [Claude Code documentation: Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp), accessed 2026-10-10
- [GitHub: ahonn/mcp-server-gsc](https://github.com/ahonn/mcp-server-gsc), accessed 2026-10-10
- [GitHub: AminForou/mcp-gsc](https://github.com/AminForou/mcp-gsc), accessed 2026-10-10