---
title: "Serql MCP server"
description: "Connect Claude, ChatGPT, Cursor, or any Model Context Protocol client to Serql: server URLs, OAuth, tools, resources, and a public documentation server."
canonical: https://www.serql.io/docs/mcp
markdown: https://www.serql.io/docs/mcp.md
last-updated: 2026-09-14
section: docs
site: "Serql"
llms: https://www.serql.io/llms.txt
---

# Serql MCP server

Serql exposes its Search Console analytics to AI assistants through the [Model Context Protocol](https://modelcontextprotocol.io) using the **Streamable HTTP** transport.

| Server | URL | Authentication | Purpose |
| --- | --- | --- | --- |
| Product | `https://www.serql.io/mcp` (alias: `https://app.serql.io/api/mcp`) | OAuth 2.0 bearer token (see https://www.serql.io/auth.md) | Act on the authorizing user's Search Console properties |
| Documentation | `https://www.serql.io/api/mcp/docs` | none | Search and read the public documentation |

Server card (name, icon, description, tools): https://www.serql.io/.well-known/mcp/server-card.json.

## Connecting

- **Claude (web/desktop):** Settings → Connectors → Add custom connector → URL `https://www.serql.io/mcp`. Claude discovers the OAuth server from the `401` challenge and opens the consent screen.
- **ChatGPT:** Settings → Connectors → Create → MCP server URL `https://www.serql.io/mcp`, authentication OAuth.
- **Cursor / VS Code / Claude Code:** add an HTTP server entry:

  ```json
  { "mcpServers": { "serql": { "url": "https://www.serql.io/mcp" } } }
  ```

  `claude mcp add --transport http serql https://www.serql.io/mcp`

- **Custom agents:** use any MCP SDK with Streamable HTTP and an OAuth 2.0 authorization-code client. The protected-resource metadata is at `https://www.serql.io/.well-known/oauth-protected-resource/mcp` (and `https://app.serql.io/.well-known/oauth-protected-resource/api/mcp` for the app-origin alias). The server card is also served at `/.well-known/mcp.json`.

Public clients register automatically when the deployment enables Client ID Metadata Documents or Dynamic Client Registration in Clerk; otherwise the operator issues a `client_id`.

## Tools (product server)

The product server registers every tool below; the documentation server registers only the `search_docs`, `get_doc`, and `list_docs` tools.

| Tool | Mode | Parameters | Description |
| --- | --- | --- | --- |
| `list_properties` | read-only | `days`?, `classification`?, `searchType`? | List every Google Search Console property the authorized user can access (owned and shared via team grants), with clicks, impressions, CTR, position, and period-over-period deltas for the requested window, a per-property KPI `status` (ok, error, needs_reconnect), plus tags, favorites, and hidden status. `periodLabel` names the window the totals cover. Call this first to obtain propertyId values for the other tools. |
| `get_performance` | read-only | `propertyId`, `startDate`, `endDate`, `compareStart`?, `compareEnd`?, `aggregation`?, `scope`?, `classification`?, `searchType`?, `filters`?, `queryLimit`?, `pageLimit`? | Fetch Search Console performance for one property over a date range: a clicks/impressions/CTR/position time series (daily, weekly, or monthly), optional comparison range, Google core-update and custom annotations, and top queries, pages, countries, topic clusters, and segments, plus CTR by position band (also without branded queries when brand terms are configured). Supports branded/non-branded and segment classifications and JSON dimension filters. |
| `get_cannibalization` | read-only | `propertyId`, `startDate`, `endDate` | Find keyword cannibalization on a property: queries where two or more pages compete for the same search term over the date range, with each page's clicks, impressions, and position so the agent can recommend consolidation. |
| `get_growth_opportunities` | read-only | `propertyId`, `startDate`, `endDate` | Surface growth opportunities for a property: queries with high impressions but weak CTR or position (striking-distance keywords) that are likely to gain clicks from on-page optimization. |
| `get_query_insights` | read-only | `propertyId`, `startDate`, `endDate` | Return trend insights for a property: rising and decaying queries and pages between the current and previous period, useful for spotting momentum or losses after Google core updates. |
| `list_annotations` | read-only | `propertyId` | List the custom annotations (site changes, campaigns, migrations) recorded on a property, each with a date, title, and optional description. |
| `create_annotation` | writes | `propertyId`, `date`, `title`, `description`? | Create a custom annotation on a property so a site change or campaign is overlaid on every performance chart. Writes data; requires member access or higher on the property. |
| `list_segments` | read-only | `propertyId` | List the saved classifications (segments) defined for a property, with their rules, so the agent can pass a segment id to get_performance as a classification. |
| `list_tags` | read-only | — | List the portfolio tags the authorized user has created for grouping properties (for example by client or business unit). |

| Tool | Mode | Parameters | Description |
| --- | --- | --- | --- |
| `search_docs` | read-only | `query`, `limit`? | Search the public product and developer documentation (REST API, MCP, authentication, self-hosting, pricing, concepts) and return the best-matching sections with links. Use it to answer 'how do I' questions about the product without guessing. |
| `get_doc` | read-only | `slug` | Fetch one documentation page as markdown by its slug (for example 'docs/api', 'docs/mcp', 'auth', 'pricing'). Use list_docs or search_docs to discover slugs. |
| `list_docs` | read-only | `section`? | List every public documentation page with its slug, title, description, and URL. |

Every tool declares a typed `inputSchema` with `required` fields and behavioural annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). Only `create_annotation` writes data, and it only creates a note inside Serql; nothing ever modifies Google Search Console.

## Resources

Both servers expose the documentation as resources with the URI template `serql://docs/{+slug}` (`text/markdown`), for example `serql://docs/docs/api` or `serql://docs/auth`. `resources/list` enumerates every page.

## Behaviour notes for agents

- Call `list_properties` first; every other product tool needs a `propertyId`.
- Search Console data lags two to three days. End ranges at "today minus 3 days" unless the user asks otherwise.
- Large tables are capped in tool responses; ask for a narrower date range or a `classification` to drill down.
- Errors come back as structured JSON with `isError: true`, a `status`, and a `hint`. `402` means the user needs a subscription; `404` means the property is not tracked or not visible.
- The server's `initialize` response includes `instructions` summarizing the above.

## Related

- REST API: https://www.serql.io/docs/api
- Authentication: https://www.serql.io/auth.md
- Agent guide: https://www.serql.io/docs/agents