# GTmetrix MCP

The official GTmetrix MCP server connects your AI tool to GTmetrix so it can run real page performance tests, read reports, track history and manage monitoring, all from a prompt.

**No GTmetrix account needed to try it.** Connect as a guest and start testing right away. Sign in to unlock more testing and features.

- **Server URL:** `https://gtmetrix.com/mcp`
- **Transport:** Streamable HTTP (remote, nothing to install)
- **Auth:** Guest (no login), OAuth, or API key via `Authorization: Bearer` header
- **Works with:** Claude, ChatGPT, Codex, Cursor, GitHub Copilot CLI and any MCP-compatible client

---

## Quick start

### Option 1: OAuth (recommended)

1. Add a new remote MCP server / custom connector in your AI tool.
2. Name it `GTmetrix` and set the URL to `https://gtmetrix.com/mcp`.
3. Click **Connect** / **Authenticate**.

No API key needed. You can also copy the MCP URL from the **MCP Setup** section of your GTmetrix Account page.

### Using it as a guest

You don't need a GTmetrix account to get started. As a guest you can run tests, read reports and look up locations, browsers and devices, using a limited number of guest credits.

When you run out of guest credits, or want features tied to an account (page history, monitoring, alerts, tags), ask your AI to sign you in. It will call `gtmetrix_reauthenticate`, and you'll get a sign-in page where you can log in or create a free account.

### Option 2: API key

Generate an API key on your GTmetrix Account page, then add it to your client's config.

**Claude Code**

```bash
claude mcp add gtmetrix https://gtmetrix.com/mcp --transport http --header "Authorization: Bearer YOUR_API_KEY"
```

**Codex (`config.toml`)**

```toml
[mcp_servers.gtmetrix]
url = "https://gtmetrix.com/mcp"

[mcp_servers.gtmetrix.http_headers]
Authorization = "Bearer YOUR_API_KEY"
```

**JSON config (Cursor and other clients that support remote HTTP servers)**

```json
{
  "mcpServers": {
    "gtmetrix": {
      "url": "https://gtmetrix.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**GitHub Copilot CLI** (OAuth only)

```
/mcp add GTmetrix
```
Set Server Type to **HTTP**, URL to `https://gtmetrix.com/mcp`, Tools to `*`, save, then authenticate in the browser.

Step-by-step guides: [Claude](https://gtmetrix.com/blog/) · [ChatGPT](https://gtmetrix.com/blog/) · [Codex](https://gtmetrix.com/blog/) · [Cursor](https://gtmetrix.com/blog/) · [Copilot CLI](https://gtmetrix.com/blog/)

---

## Example prompts

- "Test example.com from London and Sydney on an iPhone over LTE and tell me if performance is comparable."
- "Analyze my latest report for example.com and explain the top 3 issues in plain terms."
- "Give me a health check of all my monitored pages tagged 'client'. Flag anything below a B grade or with LCP over 2s."
- "Compare this week's reports for my checkout page against last month. Did anything regress?"
- "Set up daily monitoring on my homepage and alert me if LCP goes above 2.5 seconds."
- "Fix render-blocking JavaScript on my site, then rerun GTmetrix and confirm the improvement."

---

## Tools

Guests can use the Testing tools (except `gtmetrix_get_report_har`) and the Account and reference tools. The rest require a GTmetrix account.

### Testing

| Tool | What it does |
|---|---|
| `gtmetrix_start_test` | Start a test on a URL. Supports location, browser, simulated device, connection throttling, AdBlock, video, cookies, HTTP auth, URL allow/block lists, viewport size and report retention (1, 6, 12 or 24 months). |
| `gtmetrix_get_test` | Check a running test. Long-polls server-side (up to 30s per call) and returns the report ID when done. |
| `gtmetrix_get_report` | Get a finished report: GTmetrix grade, Performance and Structure scores, Core Web Vitals (LCP, TBT, CLS), top 5 Lighthouse issues ranked by impact, a resource summary, and download links for the HAR and full Lighthouse JSON. |
| `gtmetrix_get_report_har` | Return the HAR waterfall inline, for clients that can't download the HAR URL directly. Size-limited by default. |

### History and pages

| Tool | What it does |
|---|---|
| `gtmetrix_list_pages` | List your pages (URL + test settings) with latest scores, Web Vitals, monitoring status and tags. Filter by URL, location, browser, device, throttle, monitoring frequency, tags and more. |
| `gtmetrix_get_report_history` | Get every report for a page, newest first, for trend and regression analysis. |

### Monitoring and alerts

| Tool | What it does |
|---|---|
| `gtmetrix_set_page_monitoring` | Turn monitoring on (hourly, daily, weekly, monthly) or off for a page. |
| `gtmetrix_get_page_alert_conditions` | Read a page's alert conditions. |
| `gtmetrix_set_page_alert_conditions` | Set alert conditions on scores, timings (LCP, TTFB, TBT, etc.), page size, requests or CLS. |
| `gtmetrix_get_page_alert_events` | List alerts a page has triggered, with links to the reports behind them. |

### Tags

| Tool | What it does |
|---|---|
| `gtmetrix_list_page_tags` | List your tags and how many pages use each. |
| `gtmetrix_save_page_tag` | Create a tag or rename/recolor an existing one. |
| `gtmetrix_update_page_tags` | Attach or detach a tag on up to 500 pages at once. |
| `gtmetrix_delete_page_tag` | Permanently delete a tag. |

### Account and reference

| Tool | What it does |
|---|---|
| `gtmetrix_get_account_status` | Show your plan, remaining API credits and next refill date (guests see remaining guest credits). |
| `gtmetrix_get_catalog` | Look up available browsers, locations, simulated devices, throttle presets and Lighthouse audits. |
| `gtmetrix_get_guide` | Read built-in guides on test options, report analysis, HAR analysis and test errors. |
| `gtmetrix_reauthenticate` | Sign in from a guest connection, or switch to a different GTmetrix account. |

---

## Resources

The server also exposes its guides and catalogs as MCP resources:

- `gtmetrix://docs/test-options-guide`
- `gtmetrix://docs/report-analysis-guide`
- `gtmetrix://docs/har-analysis-guide`
- `gtmetrix://docs/general-test-error-guide`
- `gtmetrix://docs/lighthouse-error-guide`
- `gtmetrix://catalog/browsers`
- `gtmetrix://catalog/locations`
- `gtmetrix://catalog/simulated-devices`
- `gtmetrix://catalog/throttle-connections`
- `gtmetrix://catalog/lighthouse-audits`

---

## Credits and limits

- Anyone can use the MCP. Guests get a limited number of credits; a GTmetrix account gives you more.
- Tests and other actions use API credits at the same rate as the GTmetrix API. Video recording adds 0.9 credits per test.
- Credit allowances depend on your plan. Select PRO plans get daily credit refills. Ask your AI to run `gtmetrix_get_account_status` to see your balance.
- Concurrent tests: 2 on Basic, 8 on PRO.
- Some features (more locations, hourly monitoring, video on alerts) depend on your plan.

[See GTmetrix PRO plans](https://gtmetrix.com/pro/)

---

## FAQ

**Is this a chatbot?**
No. It's a connection layer that gives the AI tool you already use access to GTmetrix.

**Do I need a GTmetrix account?**
No. You can connect as a guest and run tests right away. Sign in to unlock more testing and features.

**Do I need an API key?**
Only for manual config. OAuth connections don't need one.

**Why aren't my results shown as charts?**
Rendering depends on your AI tool. Ask it to "visualize this data" after getting a report.

**Can it fix issues for me?**
GTmetrix provides the data and diagnostics. If your AI tool can also edit your code or CMS, it can apply fixes and rerun a test to confirm the result.

---

## Links

- [Introducing the GTmetrix MCP](https://gtmetrix.com/blog/)
- [Setup guide](https://gtmetrix.com/blog/)
- [GTmetrix API docs](https://gtmetrix.com/api/docs/)
- [Support](https://gtmetrix.com/contact.html)