<p align="center"><img src="icon.png" width="120" height="120" alt="Click Decay logo"></p>

# Click Decay: MCP server

[![Click Decay MCP connector](https://glama.ai/mcp/connectors/com.clickdecay/mcp-server/badges/score.svg)](https://glama.ai/mcp/connectors/com.clickdecay/mcp-server)

Search Console CTR comparisons inside Claude, ChatGPT, Cursor, VS Code and other MCP clients. Give it the clicks and impressions of two periods and it splits the click change into a part from impressions and a part from CTR, labels every number as observed, calculated or modelled, and checks the dates against known Google Search Console reporting issues.

- **Server URL:** `https://clickdecay.com/mcp` (use this exact host: `www.clickdecay.com` redirects, and a redirect breaks POST requests)
- **Transport:** Streamable HTTP (stateless JSON responses)
- **Authentication:** none, no API key
- **Registry name:** `com.clickdecay/mcp-server`
- **Documentation:** [clickdecay.com/mcp-server](https://clickdecay.com/mcp-server/) (Estonian: [clickdecay.com/et/mcp-server](https://clickdecay.com/et/mcp-server/))
- **Web tools:** [CTR calculator](https://clickdecay.com/ctr-calculator/) and [Search Console analysis](https://clickdecay.com/gsc-audit/)
- **Changes:** [CHANGELOG.md](CHANGELOG.md)

This repository holds the documentation and client configuration only. The server is hosted by QQQ OÜ on clickdecay.com; there is nothing to install or run.

## Tools

All four tools only read: they calculate from the numbers you give and store nothing.

| Tool | Input | Returns |
|---|---|---|
| `compare_ctr_periods` | `prior` and `current`: `start`, `end` (YYYY-MM-DD), `clicks`, `impressions`; optional `source`: `gsc_ui_export`, `bulk_export`, `api` or `other` | CTR of both periods, the change in percentage points and percent, the click and impression changes, clicks at the earlier CTR, and the split of the click change into an impressions component and a CTR component. Also the known reporting issues the dates overlap and the warnings. The periods must be the same length, must not overlap, and must have ended. |
| `project_clicks_at_ctr` | `impressions`, `ctrPercent` (0–100: 3 means 3%) | The clicks those impressions would earn at that CTR (modelled). |
| `impressions_needed_for_clicks` | `clicks`, `ctrPercent` | The impressions a click target needs at that CTR (modelled), or the reason there is no answer, such as a CTR of 0. |
| `check_gsc_reporting_issues` | optional `periods` (up to four `start`/`end` ranges), optional `source` | The known Search Console reporting issues that overlap the dates, with the affected metrics, the sources they apply to and Google's own notice. Without dates: every known issue. |

## How to read the results

- Every number is an object `{ value, evidence, nullReason, unit }`.
  - `evidence`: `observed` (arithmetic on the numbers you gave), `calculated` (exact decomposition), `modelled` (depends on an assumed CTR) or `not_established`.
  - `unit`: `ctr_fraction` (0.045 means 4.5%), `percentage_points`, `percent`, `clicks` or `impressions`.
  - `value` is unrounded. It is `null` when the quantity is undefined or withheld, and `nullReason` says why.
- From 13 May 2025 to 27 April 2026 Google logged Search Console impressions wrongly. When a period overlaps that, every figure that depends on impressions is withheld (`GSC_REPORTING_ANOMALY`) and the issue is listed with its source. Clicks are still compared.
- The split of a click change is arithmetic, not a cause. Every comparison carries the warning `NO_AI_CAUSATION`: the numbers do not show why clicks or CTR changed, or whether AI Overviews played a part.
- An input that breaks a rule, such as more clicks than impressions or overlapping periods, comes back as an error with a code and the field, so the assistant can correct it.

The formulas are in the [methodology](https://clickdecay.com/methodology/).

## Connect

[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP_server-000000?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=clickdecay&config=eyJ1cmwiOiJodHRwczovL2NsaWNrZGVjYXkuY29tL21jcCJ9) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_server-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=clickdecay&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fclickdecay.com%2Fmcp%22%7D)

### Claude (claude.ai, Claude Desktop)

Settings → Connectors → Add custom connector → URL `https://clickdecay.com/mcp`, no authentication.

### Claude Code

```bash
claude mcp add --transport http clickdecay https://clickdecay.com/mcp
```

### ChatGPT

Developer mode → Settings → Connectors → add a server with URL `https://clickdecay.com/mcp`, authentication "No authentication".

### Cursor

`~/.cursor/mcp.json` or `.cursor/mcp.json` in a project ([examples/cursor.mcp.json](examples/cursor.mcp.json)):

```json
{
  "mcpServers": {
    "clickdecay": {
      "url": "https://clickdecay.com/mcp"
    }
  }
}
```

### VS Code

`.vscode/mcp.json` ([examples/vscode.mcp.json](examples/vscode.mcp.json)):

```json
{
  "servers": {
    "clickdecay": {
      "type": "http",
      "url": "https://clickdecay.com/mcp"
    }
  }
}
```

### Windsurf

Windsurf MCP config (Cascade → MCP servers → View raw config):

```json
{
  "mcpServers": {
    "clickdecay": {
      "serverUrl": "https://clickdecay.com/mcp"
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add --transport http clickdecay https://clickdecay.com/mcp
```

### OpenAI Codex CLI

```bash
codex mcp add clickdecay --url https://clickdecay.com/mcp
```

### Clients that only support stdio

Use the `mcp-remote` bridge ([examples/claude-desktop-stdio.json](examples/claude-desktop-stdio.json)):

```json
{
  "mcpServers": {
    "clickdecay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://clickdecay.com/mcp"]
    }
  }
}
```

## Example prompts

- *"Compare 1–28 August, 5,400 clicks from 120,000 impressions, with 1–28 September, 4,100 clicks from 124,000 impressions. How much of the drop came from CTR?"* The answer: impressions added about 180 clicks and the lower CTR cost about 1,480, a change of −1,300.
- *"How many impressions do I need for 1,000 clicks at a CTR of 2.5%?"*
- *"Were there known Search Console reporting issues between March and May 2026?"*

## Plugins

This repository is also a plugin for agents that install plugins from GitHub. It bundles the remote server config and a skill that tells the agent when to use each tool:

- Claude Code: `/plugin marketplace add meelis545/clickdecay-mcp`, then `/plugin install clickdecay@clickdecay` (`.claude-plugin/`, `.mcp.json`, `skills/`)
- Cursor: `.cursor-plugin/plugin.json` and `mcp.json`
- Agent Plugins (agent-plugins.org): `plugin.json` and `mcp.json`

## Limits

| What | Limit |
|---|---|
| Requests per connection (IP address; IPv6 per /64) | about 60 a minute |
| Requests in total | about 300 a minute |
| Request body | 16 KB |

## Privacy

- The tools accept numbers, dates and the name of the data source only: no queries, page URLs, site names or files.
- Values are calculated in memory and returned. They are not stored, not logged and not used for research.
- The IP address is only the key of Cloudflare's per-minute rate limiter and is not stored.
- Search Console exports are read only in your browser on [clickdecay.com/gsc-audit](https://clickdecay.com/gsc-audit/); the MCP server takes no files.

Full notice: https://clickdecay.com/privacy/#mcp

## Protocol details

- Protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26` and older ones the official TypeScript SDK supports
- Stateless: no `Mcp-Session-Id`, no SSE stream; `GET` and `DELETE` get `405`
- CORS open (`*`): no cookies or credentials are used
- Every tool has a title, an output schema and the annotations `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- [`server.json`](server.json) is the entry in the official MCP Registry

## About

[Click Decay](https://clickdecay.com/) reads Google Search Console numbers without reading more into them than they show. It is run by QQQ OÜ, an SEO and AI search agency in Tallinn, Estonia, and written by Meelis Vill ([about](https://clickdecay.com/about/)).

## Contact

ai@qqq.ee