/semrush

name: semrush
description: Competitive SEO and traffic data from the Semrush MCP server (v2) for any domain, including ones nobody here owns — keyword search volume and difficulty, the keywords a domain ranks for, which URL ranks for a query, organic and paid competitors, keyword gaps, backlink profiles and referring domains, authority score, traffic estimates, audience demographics, and technical site audits. Covers the mandatory three-step call protocol, the JSON envelope that reports each call's API unit cost, and regional database selection. Use whenever the user mentions Semrush, keyword research, search volume, keyword difficulty, backlinks, referring domains, domain authority, competitor or competitive analysis, SERP analysis, traffic estimates, or site audit — or asks "what do we rank for", "what does this competitor rank for", "who ranks for this keyword", "how many people search for X", or "who links to them".
license: Apache-2.0
metadata:
  version: "1.0.0"

Semrush

Estimated, third-party SEO data for any domain — yours or a competitor's. Reached through the Semrush MCP server at `https://mcp.semrush.com/v2/mcp`, which exposes 14 tools and 86 reports.

Setup

Register the server with your agent once. OAuth runs on first contact and needs a human at the browser to approve it.

mcp add https://mcp.semrush.com/v2/mcp semrush     # adjust for your own agent

That command is one agent's syntax. Substitute whatever your agent uses to add a remote MCP server; the only things that matter are the URL and that the OAuth authorization-code flow (scope `mcp.access`) completes. Semrush allowlists redirect URIs — see [references/protocol.md](references/protocol.md) if registration is rejected.

A legacy `v1` endpoint also answers, with different tool names, different parameter names and bare CSV instead of the envelope below; Semrush advertises only v2.

Everything below is expressed as MCP **tool calls**, written as `tool_name(arg=value)`. Issue them however your agent invokes MCP tools.

Three steps, never fewer

This is the one thing agents get wrong. A toolkit tool such as `domain_overview` returns **no data**. It returns a catalogue of reports with descriptions and a `suggested_call` pointing at the next step.

1. domain_overview()                                -> reports[] with names + descriptions
2. get_report_schema(report="domain_rank")           -> parameters, types, enums, defaults
3. execute_report(report="domain_rank",
                  params={target: "example.com", database: "us"})   -> the data

Step 3 is the only step that returns data and the only step that spends units. Skip step 1 when you already know the report name (the tables below are that knowledge). Do not skip step 2 for a report you have not called before: parameter names differ between reports in ways that are not guessable.

The report name passed to `get_report_schema` and `execute_report` is the bare name from `reports[].name`, with no toolkit prefix — `geo`, never `audience.geo`.

The response envelope

Every successful report returns JSON, not bare text:

{"data": "Domain;Rank;Organic Keywords;...\nadobe.com;51;9866369;43299118;...\n",
 "metadata": {"format": "csv",
              "url": "https://www.semrush.com/analytics/overview/?db=us&q=adobe.com",
              "usage": {"api_units": 10}}}

Three things to do with it every time:

1. **Switch on `metadata.format`.** For `csv`, `data` is a string: header line then one line per row, `;`-separated. For `json`, `data` is already a parsed object or array. Both occur — `site_audit` and `projects` reports are `json`, analytics reports are `csv`. Do not assume. 2. **Keep `metadata.url`.** It is a canonical Semrush interface link for the same query. Cite it when reporting a figure to a human, so they can check it. 3. **Read `metadata.usage.api_units`.** That is the measured cost of the call you just made. Accumulate it and report the total.

Within a CSV `data` string, a field can itself contain commas: the `Trends` column is a comma-separated series inside a semicolon-separated row.

Which tool and report answer which question

The 14 tools: `domain_overview`, `organic_research`, `paid_search_research`, `competitors_research`, `keyword_research`, `backlinks_research`, `traffic_overview`, `audience_research`, `shopping_research`, `position_tracking`, `site_audit`, `projects`, plus `get_report_schema` and `execute_report`. The names map onto questions directly, and `execute_report` reaches every report regardless of which toolkit lists it.

| Question | Report | Toolkit | |---|---|---| | What keywords does this rank for? | `resource_organic` | organic_research | | Which of its pages earn the organic traffic? | `resource_organic_unique` | organic_research | | What changed — new, lost, rising, falling? | `resource_organic` + `display_positions` | organic_research | | Summary counters for a domain | `domain_rank` | domain_overview | | Growing or shrinking, month by month? | `resource_rank_history` | domain_overview | | Which countries does it rank in at all? | `domain_ranks` | domain_overview | | Who ranks for this keyword, with which URL? | `phrase_organic` | keyword_research | | How much searched, how hard, what intent? | `phrase_this` | keyword_research | | Same for a list of keywords in one call | `phrase_these` | keyword_research | | What else could I target around this theme? | `phrase_related`, `phrase_fullsearch`, `phrase_questions` | keyword_research | | Who are the organic competitors? | `domain_organic_organic` | competitors_research | | Who competes on paid search? | `domain_adwords_adwords` | competitors_research | | What do they rank for that we do not? | `domain_domains` | competitors_research | | Who is gaining or losing in this market? | `rank_difference` | competitors_research | | How strong is the backlink profile? | `backlinks_overview` | backlinks_research | | Who links to it, an