The GTmetrix MCP connector routes your AI agent's tool calls to GTmetrix's own MCP server through Scalekit. Each user signs in to GTmetrix once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 18 tools.
- Tools
- 18
- What they doRead · write · destructive
- 8 · 8 · 28 read8 write2 destructive
- Users sign in with
- OAuth
- OAuth app
- Scalekit's or your own
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the GTmetrix MCP connection
In AgentKit > Connections, create a GTmetrix MCP connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Scalekit credentials are available for GTmetrix MCP server, so you don't need to register an OAuth app.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'gtmetrixmcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize GTmetrix MCP:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'gtmetrixmcp_get_account_status',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "gtmetrixmcp"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize GTmetrix MCP:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="gtmetrixmcp_get_account_status",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolgtmetrixmcp_get_account_statusReturns the current GTmetrix account status including plan type, remaining API credits, next refill date, and feature access flags.Read-onlyGetAccountStatus
Returns the current GTmetrix account status including plan type, remaining API credits, next refill date, and feature access flags.
Inputs
This tool takes no inputs.
gtmetrixmcp_get_catalogFetch a GTmetrix lookup catalog in JSON format for resolving names to IDs.Read-onlyGetCatalog
Fetch a GTmetrix lookup catalog in JSON format for resolving names to IDs. Available catalogs: browsers, locations, simulated-devices, throttle-connections, lighthouse-audits.
Inputs
catalog_idstringrequired- The catalog to retrieve.one of
browserslocationssimulated-devicesthrottle-connectionslighthouse-audits
gtmetrixmcp_get_guideFetch a GTmetrix documentation guide in markdown format.Read-onlyGetGuide
Fetch a GTmetrix documentation guide in markdown format. Available guides: har-analysis, test-options, report-analysis, general-test-error, lighthouse-error.
Inputs
guide_idstringrequired- The identifier of the guide to fetch.one of
har-analysistest-optionsreport-analysisgeneral-test-errorlighthouse-error
gtmetrixmcp_get_reportRetrieve the report data using the report ID.Read-onlyGetReport
Retrieve the report data using the report ID. Contains GTmetrix scores, Core Web Vitals, top Lighthouse issues, resource summary, and download URLs.
Inputs
report_idstringrequired- The 8-character report ID to retrieve.
gtmetrixmcp_get_report_harFetch the raw HAR (net.har) for a completed GTmetrix report and return it inline.Read-onlyGetReportHar
Fetch the raw HAR (net.har) for a completed GTmetrix report and return it inline. Use when direct download of the HAR URL is not possible.
Inputs
report_idstringrequired- A GTmetrix report identifier (8 characters, e.g. hDjmzKIf).
forceboolean- Bypass the size limit and return the HAR regardless of size. WARNING: a large HAR (often several MB) can overflow the model context window â only set this if you understand the cost.default
false
gtmetrixmcp_get_report_historyFetch historical performance data for a GTmetrix page.Read-onlyGetReportHistory
Fetch historical performance data for a GTmetrix page. Returns all reports in reverse chronological order for trend analysis.
Inputs
limitinteger- Maximum number of successful reports to return, newest first (default 200, max 500). Capped by the account plan's history limit.
page_idstring- A GTmetrix page identifier. Use when you already have the page id from a previous call. Provide either report_id OR page_id â not both.
report_idstring- A GTmetrix report identifier (e.g. hDjmzKIf). The page that owns this report is looked up automatically. Provide either report_id OR page_id â not both.
gtmetrixmcp_get_testGet the current status of a started GTmetrix test.Read-onlyGetTest
Get the current status of a started GTmetrix test. Long-polls server-side until the test completes or budget expires.
Inputs
test_idstringrequired- The 8-character test ID returned by gtmetrix_start_test.
wait_secondsinteger- Number of seconds to wait for the test to complete (0–30). If omitted, returns immediately with current status.
gtmetrixmcp_list_pagesList GTmetrix pages for the authenticated account.Read-onlyListPages
List GTmetrix pages for the authenticated account. A page is a URL and test-settings combination. Returns pages with latest scores, Core Web Vitals, and monitoring status.
Inputs
adblockboolean- Pass true to show only pages with AdBlock enabled.
anonymize_user_agentboolean- Pass true to show only pages with anonymized user agent.
browserstring- Exact browser ID. Use gtmetrix_get_catalog with catalog_id='browsers' to resolve a name to an ID.
cookiesboolean- Pass true to show only pages with cookies configured.
dnsboolean- Pass true to show only pages with custom DNS overrides configured.
filterboolean- Pass true to show only pages with URL allow/block filtering configured.
httpauthboolean- Pass true to show only pages with HTTP authentication configured.
limitinteger- Maximum number of pages to return (default 200, max 2000).
locationstring- Exact location/region ID. Use gtmetrix_get_catalog with catalog_id='locations' to resolve a name to an ID.
monitoringstring- Filter by monitoring frequency: 'none' (not monitored; 'no' and 'never' are accepted as aliases), 'hourly', 'daily', 'weekly', or 'monthly'.one of
nonenoneverhourlydailyweeklymonthly privateboolean- Pass true to show only private pages. Omit to include all pages regardless of visibility.
simulate_devicestring- Exact simulated device ID. Use gtmetrix_get_catalog with catalog_id='simulated-devices' for valid IDs.
stop_onloadboolean- Pass true to show only pages that stop test at window.onload.
tagstring- Substring match against tag names. Shows only pages that have at least one tag whose name contains this string. Useful for discovery; for exact filtering use `tag_ids` instead.
tag_idsarray- Exact tag ids (from `tags[].tag_id`) the page must have ALL of â unlike `tag`, no substring/any-match. Same semantics as the REST API's filter[page_tag] and the Dashboard's tag filter.
throttlestring- Exact throttle connection string in 'down_kbps/up_kbps/latency_ms' format (e.g. '20000/5000/0'). Use gtmetrix_get_catalog with catalog_id='throttle-connections' for preset values.
urlstring- Substring match against the page URL (case-insensitive). E.g. 'example.com' matches any page whose URL contains that string.
videoboolean- Pass true to show only pages with video recording enabled.
gtmetrixmcp_gtmetrix_get_page_alert_conditionsFetch the performance-alert conditions currently configured for a GTmetrix page: whether a video is kept when an alert triggers, the metric/operator/threshold conditions, and (for Team organizations) the recipients notified.WriteGtmetrix Get Page Alert Conditions
Fetch the performance-alert conditions currently configured for a GTmetrix page: whether a video is kept when an alert triggers, the metric/operator/threshold conditions, and (for Team organizations) the recipients notified. The output matches the input of gtmetrix_set_page_alert_conditions except for each condition's display-only value_fmt, which must be dropped before passing conditions back. Use gtmetrix_get_page_alert_events to see events already triggered by these conditions. Requires a GTmetrix account - not available to guest connections; call gtmetrix_reauthenticate to sign in.
Inputs
page_idstringrequired- Stable page identifier, as returned by gtmetrix_list_pages.
gtmetrixmcp_gtmetrix_get_page_alert_eventsFetch the performance-alert events triggered by a GTmetrix page, so an agent can investigate why a page alerted.WriteGtmetrix Get Page Alert Events
Fetch the performance-alert events triggered by a GTmetrix page, so an agent can investigate why a page alerted. Each event is either a triggered condition (metric/operator/threshold, plus the actual value - both raw and human-readable) or a report-generation failure. Includes the report_id for events backed by a report - pass it as gtmetrix_get_report's report_id to see the full report that triggered the alert. Use gtmetrix_get_page_alert_conditions to see what conditions are currently configured for the page. Supports pagination via page/limit (mirrors the REST API's page[number]/page[size]); results are returned in chronological order (oldest first) within each page. Requires a GTmetrix account - not available to guest connections; call gtmetrix_reauthenticate to sign in.
Inputs
page_idstringrequired- Stable page identifier, as returned by gtmetrix_list_pages.
limitinteger- Maximum number of alert events per page (maps to the API's page[size]; default 50, max 500).
pageinteger- Page number to fetch, newest page first (maps to the API's page[number]; default 1).
gtmetrixmcp_gtmetrix_save_page_tagCreate a page tag, or update one by passing its tag_id (an upsert, matching the REST API's POST /page_tags).WriteGtmetrix Save Page Tag
Create a page tag, or update one by passing its tag_id (an upsert, matching the REST API's POST /page_tags). Updates are a partial merge â an omitted name/description/color keeps its current value; pass an empty description to clear it. Tag names are unique per account: creating with a name that's already in use fails with the existing tag's tag_id so you can update it instead. Color accepts 3 or 6 character hex, with or without a leading '#' (e.g. 'f80', '#ff8800'); it's normalized and always returned as 6 characters with no '#'. New accounts have a limited number of tags â see gtmetrix_list_page_tags for the current count before creating more. Use gtmetrix_update_page_tags to attach/detach the saved tag from pages, and gtmetrix_delete_page_tag to remove it. Requires a GTmetrix account with at least Tester-level org access (Team organizations) â not available to guest connections; call gtmetrix_reauthenticate to sign in.
Inputs
colorstring- Tag background color: a 3 or 6 character hex value, with or without a leading '#' (e.g. 'f80', '#f80', 'ff8800'). Defaults to white ('FFFFFF') on create; on update, omitting it keeps the current color.
descriptionstring- Tag description, shown as a tooltip on hover. On update, omit to keep the current description, or pass an empty string to clear it.
namestring- Tag name, unique per account. Required when creating (tag_id omitted); optional when updating, where omitting it keeps the current name.
tag_idstring- Tag to update, as returned by gtmetrix_list_page_tags' tag_id. Omit to create a new tag.
gtmetrixmcp_gtmetrix_set_page_alert_conditionsReplace the performance-alert conditions configured for a GTmetrix page: which metrics trigger an alert, whether a video is kept, and (for Team organizations) who gets notified.WriteGtmetrix Set Page Alert Conditions
Replace the performance-alert conditions configured for a GTmetrix page: which metrics trigger an alert, whether a video is kept, and (for Team organizations) who gets notified. Always replaces the full condition list - pass an empty conditions array to remove all alert conditions (the same effect as the API's DELETE endpoint). create_video is also replaced, defaulting to false when omitted. Call gtmetrix_get_page_alert_conditions first to see the current config; its output matches this tool's input once each condition's value_fmt is dropped. Each condition's value must be given in the unit for its metric: seconds: speed_index, redirect_time, connect_time, backend_time, ttfb, dom_interactive, dom_content_loaded, dom_content_loaded_time, onload, onload_time, fully_loaded, first_paint, first_contentful_paint, largest_contentful_paint, time_to_interactive, total_blocking_time; percent, 0-100: gtmetrix_score, performance_score, structure_score, pagespeed_score, yslow_score; bytes: html_size, total_size; raw value, no unit conversion: rum_speed_index, requests, cumulative_layout_shift. send_to is only available - and required - for Team organizations; recipient e-mails must match an existing Team organization member's account e-mail. Requires a GTmetrix account - not available to guest connections; call gtmetrix_reauthenticate to sign in.
Inputs
conditionsarrayrequired- The full list of alert conditions for this page. Always replaces the current list â pass an empty array to remove all alert conditions.
page_idstringrequired- Stable page identifier, as returned by gtmetrix_list_pages.
create_videoboolean- Keep a video recording of the page load when an alert triggers (PRO only). Defaults to false when omitted, which turns video off even if it is currently on - pass the current value from gtmetrix_get_page_alert_conditions to keep it.default
false send_toarray- Recipients to notify on alert. Required for Team organizations, otherwise omit entirely.
gtmetrixmcp_gtmetrix_set_page_monitoringEnable or disable recurring monitoring for a GTmetrix page, which re-runs its saved test settings on a schedule and keeps each run as a report.WriteGtmetrix Set Page Monitoring
Enable or disable recurring monitoring for a GTmetrix page, which re-runs its saved test settings on a schedule and keeps each run as a report. Requires page_id (from gtmetrix_list_pages) and frequency: 'none' to disable ('no' and 'never' are accepted as aliases), or 'hourly', 'daily', 'weekly', 'monthly' to enable at that cadence. Monitoring is plan-limited (a fixed number of monitoring slots, plus hourly-access and region/browser coverage restrictions) - use gtmetrix_list_pages with the monitoring filter to see which pages are currently monitored before changing this. On failure the error names the specific limit hit, e.g. '3 of 3 monitoring slots in use'. Returns the updated page in the same shape gtmetrix_list_pages emits for a single page, so the new state can be confirmed. Requires a GTmetrix account - not available to guest connections; call gtmetrix_reauthenticate to sign in.
Inputs
frequencystringrequired- Monitoring cadence to apply: 'none' (not monitored; 'no' and 'never' are accepted as aliases), 'hourly', 'daily', 'weekly', or 'monthly'. Anything other than 'none' enables monitoring at that cadence.one of
nonenoneverhourlydailyweeklymonthly page_idstringrequired- Stable page identifier, as returned by gtmetrix_list_pages.
gtmetrixmcp_start_testStart a new GTmetrix page performance test for a URL.WriteStartTest
Start a new GTmetrix page performance test for a URL.
Inputs
urlstringrequired- No description.
adblockboolean- No description.one of
truefalse0101default0 allow_urlarray- No description.
anonymize_user_agentboolean- No description.one of
truefalse0101default0 block_urlarray- No description.
browserstring- No description.
browser_dppxnumber- No description.
browser_heightinteger- No description.default
768 browser_rotateboolean- No description.one of
truefalse0101 browser_widthinteger- No description.default
1366 cookiesarray- No description.
dnsarray- No description.
httpauth_passwordstring- No description.
httpauth_usernamestring- No description.
locationstring- No description.default
24 reportstring- No description.one of
lighthouselegacynonelighthouse,legacy retentionnumber- No description.one of
161224default1 simulate_devicestring- No description.
stop_onloadboolean- No description.one of
truefalse0101default0 throttlestring- Throttle the connection, formatted as 'down_kbps/up_kbps/latency_ms' (e.g. '1600/768/300' â a slow 3G link). Presets via gtmetrix_get_catalog with catalog_id='throttle-connections'.
user_agentstring- No description.
videoboolean- No description.one of
truefalse0101default0
gtmetrixmcp_gtmetrix_delete_page_tagPermanently delete a page tag: irreversible.DestructiveGtmetrix Delete Page Tag
Permanently delete a page tag: irreversible. Removes the tag from every page that had it (including from any saved report filters that reference it) and deletes the tag itself â there is no undo. Find the tag_id with gtmetrix_list_page_tags first (its page_count tells you how many pages will be affected) if you're not certain which tag this is. To rename or recolor a tag instead, use gtmetrix_save_page_tag with its tag_id. Requires a GTmetrix account with at least Tester-level org access (Team organizations) â not available to guest connections; call gtmetrix_reauthenticate to sign in.
Inputs
tag_idstringrequired- The tag to delete, as returned by gtmetrix_list_page_tags' tag_id.
gtmetrixmcp_reauthenticateSign in to a GTmetrix account from the current MCP session.DestructiveReauthenticate
Sign in to a GTmetrix account from the current MCP session. Call this when a guest connection hits the guest credit limit (a 402 'Insufficient guest credits' error) or is told that a tool requires a GTmetrix account, and also when a logged-in user wants to switch accounts. It revokes the current access token; on the next GTmetrix tool call the server will require re-authentication and present a sign-in page where the user can log into (or create) an account.
- Idempotent
Inputs
This tool takes no inputs.
No tools match.
