Semrush MCP
Provides tools for keyword research, domain analytics, backlink analysis, traffic analytics, audience intelligence, and competitive intelligence via the Semrush API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Semrush MCP domain overview for semrush.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Semrush MCP
MCP Server & CLI for keyword research, domain analytics, backlinks, traffic analysis, and competitive intelligence.
A community-maintained, self-hosted tool that provides Semrush API data through two entry points: an MCP server for AI assistants like Claude Desktop and Cursor, and a semrush CLI for direct terminal use — ideal for developers and AI coding agents like Claude Code that can run shell commands on your behalf. One install gives you both.
Quick Start
npm install -g github:mrkooblu/semrush-mcp
export SEMRUSH_API_KEY=your_api_key_hereAfter installing, you have two commands:
semrush— CLI for terminal and agent usesemrush-mcp— MCP server on stdio for AI clients
CLI:
semrush domain semrush.com # Domain overview
semrush kw "seo tools" # Keyword overview
semrush backlinks semrush.com # Backlink analysisMCP server (add to your AI client config):
{
"mcpServers": {
"semrush-mcp": {
"command": "npx",
"args": ["-y", "github:mrkooblu/semrush-mcp"],
"env": {
"SEMRUSH_API_KEY": "your-api-key"
}
}
}
}Related MCP server: semrush-mcp
Features
Domain Analytics — Overview, rank tracking, rank history, organic/paid keywords, competitors, ads history, shopping, unique pages
URL Analytics — Organic/paid keywords, rank, rank history per URL
Subdomain Analytics — Rank, rank history, organic keywords per subdomain
Subfolder Analytics — Organic/paid keywords, rank, rank history, unique pages per subfolder
Keyword Research — Overview, related keywords, broad match, questions, SERP organic/paid results, ads history, difficulty
Backlink Analysis — Backlinks, referring domains, overview, pages, anchors, TLD distribution, categories
Traffic Analytics — Summary, sources, destinations, geo, subdomains, subfolders, top pages, rank, social media (requires .Trends)
Audience Intelligence — Audience insights, demographics, purchase conversion, interests (requires .Trends)
Projects API — List, create, update, delete projects
Site Audit — Audit info, snapshots, issues, pages, history, launch crawls
Keyword Gap Analysis — Compare two domains' keyword profiles side by side (CLI only)
API Units Balance — Check remaining API credits
All capabilities are available through both the MCP server (77 tools) and the CLI.
Installation
Install globally from GitHub
npm install -g github:mrkooblu/semrush-mcpOr clone and link locally
git clone https://github.com/mrkooblu/semrush-mcp.git
cd semrush-mcp
npm install && npm run build && npm linkSet your API key in the environment or a .env file:
export SEMRUSH_API_KEY=your_api_key_hereMCP Setup
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"semrush-mcp": {
"command": "npx",
"args": ["-y", "github:mrkooblu/semrush-mcp"],
"env": {
"SEMRUSH_API_KEY": "your-api-key"
}
}
}
}Cursor
Go to Settings > MCP Servers > Add Server
Configure:
Name:
Semrush MCPType:
commandCommand:
nodeArguments:
/path/to/semrush-mcp/dist/index.jsEnvironment Variables:
SEMRUSH_API_KEY=your_api_key
Other MCP Clients
Any MCP-compatible client can connect using stdio transport. Point it at semrush-mcp or node dist/index.js with the SEMRUSH_API_KEY environment variable set.
CLI Usage
The semrush CLI is built for both human use and AI coding agents like Claude Code that can invoke shell commands directly. All commands support -d, --database <db> (country code, default: us), -l, --limit <n>, and -f, --format <text|json>.
Quick Overview
Auto-detects keyword vs domain:
semrush q "seo tools" # Keyword overview
semrush q example.com # Domain overviewDomain Analytics
semrush domain semrush.com # Domain overview
semrush d example.com --organic -l 30 # Organic keywords
semrush d example.com --paid -l 20 # Paid keywords
semrush d example.com --competitors -l 10 # CompetitorsKeyword Research
semrush kw "content marketing" # Basic overview
semrush kw "seo" --related -l 20 # Related keywords
semrush kw "marketing" --questions -l 10 # Question-based keywords
semrush kw "email marketing" --broad -l 15 # Broad match keywords
semrush kw "seo tools" --organic -l 10 # SERP organic results
semrush kw "ppc software" --paid -l 10 # SERP paid resultsKeyword Difficulty
semrush kd "seo" "content marketing" "link building"Backlinks
semrush bl example.com # Backlink overview
semrush bl example.com --domains -l 20 # Referring domainsTraffic Analytics
Requires .Trends API subscription.
semrush traffic example.com # Traffic summary
semrush traffic example.com --sources # Traffic sourcesKeyword Gap Analysis
semrush gaps mysite.com competitor.com -l 50API Units Balance
semrush unitsAvailable MCP Tools
Domain Analytics (13 tools)
Tool | Description |
| Domain overview — traffic, keywords, rankings across all databases |
| Domain rank in a specific database |
| Historical rank data for a domain |
| Domains with biggest rank changes |
| Organic keywords for a domain |
| Paid keywords for a domain |
| Organic search competitors |
| Paid search competitors |
| Domain's ad history over time |
| Unique organic pages for a domain |
| Unique paid ad pages for a domain |
| Shopping/PLA keywords for a domain |
| Unique shopping ad pages |
URL Analytics (5 tools)
Tool | Description |
| Organic keywords for a specific URL |
| Paid keywords for a specific URL |
| Rank data for a specific URL |
| Historical rank data for a URL |
| Rank across all databases for a URL |
Subdomain Analytics (4 tools)
Tool | Description |
| Rank data for a subdomain |
| Rank across all databases for a subdomain |
| Historical rank data for a subdomain |
| Organic keywords for a subdomain |
Subfolder Analytics (7 tools)
Tool | Description |
| Organic keywords for a subfolder |
| Paid keywords for a subfolder |
| Rank data for a subfolder |
| Rank across all databases for a subfolder |
| Historical rank data for a subfolder |
| Unique organic pages in a subfolder |
| Unique paid ad pages in a subfolder |
Backlinks (7 tools)
Tool | Description |
| Backlinks for a domain/URL |
| Referring domains |
| Backlinks summary stats |
| Pages with most backlinks |
| Anchor text distribution |
| TLD distribution of backlinks |
| Category distribution of backlinks |
Keyword Research (10 tools)
Tool | Description |
| Keyword overview across all databases |
| Detailed keyword data for specific database |
| Analyze up to 100 keywords at once |
| Related keyword discovery |
| Broad match / alternate queries |
| Question-based keywords |
| Domains ranking in organic results |
| Domains in paid search results |
| 12-month history of domains bidding on a keyword |
| Difficulty index for ranking in top 10 |
Traffic & Audience (17 tools, requires .Trends subscription)
Tool | Description |
| Traffic summary for domains |
| Traffic sources breakdown |
| Where traffic goes after visiting |
| Geographic distribution of traffic |
| Traffic by subdomain |
| Traffic by subfolder |
| Highest-traffic pages |
| Traffic rank over time |
| Social media traffic breakdown |
| Audience overlap between domains |
| Purchase conversion metrics |
| Household size demographics |
| Income demographics |
| Education level demographics |
| Occupation demographics |
| Audience interest categories |
| Traffic data accuracy estimates |
Projects & Site Audit (13 tools)
Tool | Description |
| List all projects |
| Get project details |
| Create a new project |
| Update project settings |
| Delete a project |
| Site audit configuration and status |
| List audit snapshots |
| Get snapshot details |
| Audit issue metadata |
| List audited pages |
| Page-level audit details |
| Audit history |
| Launch a new audit crawl |
Utility (1 tool)
Tool | Description |
| Check API units balance |
CLI-Only Commands
CLI Command | Description |
| Keyword gap analysis between two domains |
Configuration
Requires SEMRUSH_API_KEY in environment or .env file.
Variable | Default | Description |
| (required) | Your Semrush API key |
| 300 | Cache TTL for API responses |
| 10 | Maximum API requests per second |
| development | Environment mode |
| info | Logging level |
API Units Consumption
API requests consume units from your Semrush account. Different reports have different costs:
Tool | API Units per Line |
| 10 |
| 10 |
| 10 |
| 10 |
| 20 |
| 20 |
| 40 |
| 40 |
| 50 |
| 100 |
Check your balance anytime with semrush units or the semrush_api_units_balance MCP tool.
Development
git clone https://github.com/mrkooblu/semrush-mcp.git
cd semrush-mcp
npm install
cp .env.example .env # add your SEMRUSH_API_KEYnpm run dev # MCP server in dev mode (tsx, hot reload)
npm run build # Compile TypeScript to dist/
npm test # Run all tests
npm run test:unit # Unit tests only (no API key needed)
npm run test:integration # Integration tests (requires SEMRUSH_API_KEY)
npm run lint # ESLint
npm run format # PrettierGit Hooks
This project uses Husky for git hooks:
Pre-commit: lint-staged, ESLint, TypeScript type-check, unit tests, secret detection
Pre-push: uncommitted changes check, full build, integration tests (requires
SEMRUSH_API_KEY)
Why Self-Host?
This self-hosted tool is for users who need more control:
Full control over API calls and caching — configure TTL, inspect raw responses
Custom rate limiting — set your own requests-per-second limits
Self-hosted / air-gapped — runs entirely on your machine, no external MCP endpoint
CLI for agents — AI coding agents can invoke
semrushdirectly without MCPOpen source — MIT licensed, fork and customize to your needs
Security
Never share your Semrush API key publicly
API key provides access to your API units balance
Exposing credentials can lead to unauthorized API usage and unexpected charges
Hosted Alternative
Semrush also offers an official hosted MCP connector at https://mcp.semrush.com/v1/mcp — no setup required, authenticate with your Semrush account. See Getting Started with MCP for details.
This is a personal project and not an official Semrush product.
License
Available Tools
77 toolssemrush_api_units_balanceARead-onlyIdempotent
Check the remaining API units balance
Inputs: no named parameters.
semrush_audience_insightsCRead-onlyIdempotent
Get audience overlap and similarity data between domains (requires .Trends)
Inputs: targets (required), selected_targets (required), limit.
semrush_audience_interestsCRead-onlyIdempotent
Get audience interest categories for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_backlinksCRead-onlyIdempotent
Get backlinks for a specific domain or URL
Inputs: target (required), limit.
semrush_backlinks_anchorsCRead-onlyIdempotent
Get anchor text distribution for a target
Inputs: target (required), target_type, limit.
semrush_backlinks_categoriesBRead-onlyIdempotent
Get domain categories for a target based on backlinks
Inputs: target (required), target_type, limit.
semrush_backlinks_domainsBRead-onlyIdempotent
Get referring domains for a specific domain or URL
Inputs: target (required), limit.
semrush_backlinks_overviewCRead-onlyIdempotent
Get backlinks overview summary stats for a target
Inputs: target (required), target_type, limit.
semrush_backlinks_pagesCRead-onlyIdempotent
Get indexed pages with backlink data for a target
Inputs: target (required), target_type, limit.
semrush_backlinks_tldCRead-onlyIdempotent
Get referring domains by TLD for a target
Inputs: target (required), target_type, limit.
semrush_batch_keyword_overviewARead-onlyIdempotent
Analyze up to 100 keywords at once in a specific database (10 API units per line)
Inputs: keywords (required), database.
semrush_broad_match_keywordsBRead-onlyIdempotent
Get broad matches and alternate search queries for a keyword (20 API units per line)
Inputs: keyword (required), database (required), limit.
semrush_competitorsBRead-onlyIdempotent
Get competitors for a specific domain in organic search
Inputs: domain (required), database, limit.
semrush_create_projectC
Create a new Semrush project
Inputs: url (required), project_name.
semrush_delete_projectCDestructive
Delete a Semrush project
Inputs: project_id (required).
semrush_domain_ads_historyCRead-onlyIdempotent
Get ads history for a domain over last 12 months
Inputs: domain (required), database, limit.
semrush_domain_adwords_uniqueCRead-onlyIdempotent
Get unique paid ads for a domain
Inputs: domain (required), database, limit.
semrush_domain_organic_keywordsCRead-onlyIdempotent
Get organic keywords for a specific domain
Inputs: domain (required), database, limit.
semrush_domain_organic_uniqueBRead-onlyIdempotent
Get unique organic keywords grouped by URL for a domain
Inputs: domain (required), database, limit.
semrush_domain_overviewCRead-onlyIdempotent
Get domain overview data including organic/paid search traffic, keywords, and rankings
Inputs: domain (required), database, limit.
semrush_domain_paid_keywordsCRead-onlyIdempotent
Get paid keywords for a specific domain
Inputs: domain (required), database, limit.
semrush_domain_rankCRead-onlyIdempotent
Get domain ranking in a specific database
Inputs: domain (required), database, limit.
semrush_domain_rank_historyCRead-onlyIdempotent
Get historical ranking data for a domain
Inputs: domain (required), database, limit.
semrush_domain_shoppingCRead-onlyIdempotent
Get PLA (Product Listing Ads) search keywords for a domain
Inputs: domain (required), database, limit.
semrush_domain_shopping_uniqueCRead-onlyIdempotent
Get unique shopping ads for a domain
Inputs: domain (required), database, limit.
semrush_education_distributionBRead-onlyIdempotent
Get education level distribution of audience (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_get_projectCRead-onlyIdempotent
Get details of a specific Semrush project
Inputs: project_id (required).
semrush_household_distributionCRead-onlyIdempotent
Get household size distribution of audience (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_income_distributionCRead-onlyIdempotent
Get income distribution of audience (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_keyword_ads_historyBRead-onlyIdempotent
Get domains that bid on a keyword in the last 12 months (100 API units per line)
Inputs: keyword (required), database (required), limit.
semrush_keyword_difficultyARead-onlyIdempotent
Get difficulty index for ranking in Google's top 10 (50 API units per line)
Inputs: keywords (required), database.
semrush_keyword_organic_resultsBRead-onlyIdempotent
Get domains ranking in Google's top 100 for a keyword (10 API units per line)
Inputs: keyword (required), database (required), limit.
semrush_keyword_overviewCRead-onlyIdempotent
Get overview data for a specific keyword
Inputs: keyword (required), database, limit.
semrush_keyword_overview_single_dbCRead-onlyIdempotent
Get detailed overview data for a keyword from a specific database (10 API units per line)
Inputs: keyword (required), database (required), limit.
semrush_keyword_paid_resultsCRead-onlyIdempotent
Get domains in Google's paid search results for a keyword (20 API units per line)
Inputs: keyword (required), database (required), limit.
semrush_list_projectsARead-onlyIdempotent
List all Semrush projects
Inputs: no named parameters.
semrush_occupation_distributionCRead-onlyIdempotent
Get occupation distribution of audience (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_paid_competitorsBRead-onlyIdempotent
Get paid search competitors for a domain
Inputs: domain (required), database, limit.
semrush_phrase_questionsCRead-onlyIdempotent
Get question-based keywords related to a term (40 API units per line)
Inputs: keyword (required), database (required), limit.
semrush_purchase_conversionARead-onlyIdempotent
Get purchase conversion rate for a domain (requires .Trends, desktop only)
Inputs: target (required), country, display_date, limit.
semrush_rank_differenceCRead-onlyIdempotent
Get winners and losers — domains with biggest ranking changes
Inputs: database, limit.
semrush_site_audit_historyCRead-onlyIdempotent
Get site audit crawl history
Inputs: project_id (required), limit, offset.
semrush_site_audit_infoCRead-onlyIdempotent
Get site audit information for a project
Inputs: project_id (required).
semrush_site_audit_issuesCRead-onlyIdempotent
Get issue metadata for site audit
Inputs: project_id (required).
semrush_site_audit_launchC
Launch a new site audit crawl for a project
Inputs: project_id (required).
semrush_site_audit_page_detailBRead-onlyIdempotent
Get detailed audit data for a specific page
Inputs: project_id (required), page_id (required).
semrush_site_audit_pagesCRead-onlyIdempotent
List pages from a site audit
Inputs: project_id (required), url (required), limit, page.
semrush_site_audit_snapshot_detailCRead-onlyIdempotent
Get detailed site audit snapshot data
Inputs: project_id (required), snapshot_id (required).
semrush_site_audit_snapshotsCRead-onlyIdempotent
List site audit snapshots for a project
Inputs: project_id (required).
semrush_subdomain_organicCRead-onlyIdempotent
Get organic keywords for a subdomain
Inputs: subdomain (required), database, limit.
semrush_subdomain_rankCRead-onlyIdempotent
Get ranking data for a subdomain in a specific database
Inputs: subdomain (required), database, limit.
semrush_subdomain_rank_historyBRead-onlyIdempotent
Get historical ranking data for a subdomain
Inputs: subdomain (required), database, limit.
semrush_subdomain_ranksBRead-onlyIdempotent
Get ranking data for a subdomain across all databases
Inputs: subdomain (required), limit.
semrush_subfolder_adwordsCRead-onlyIdempotent
Get paid keywords for a subfolder
Inputs: subfolder (required), database, limit.
semrush_subfolder_adwords_uniqueCRead-onlyIdempotent
Get unique paid ads for a subfolder
Inputs: subfolder (required), database, limit.
semrush_subfolder_organicBRead-onlyIdempotent
Get organic keywords for a subfolder (e.g. domain.com/blog/)
Inputs: subfolder (required), database, limit.
semrush_subfolder_organic_uniqueBRead-onlyIdempotent
Get unique organic keywords grouped by URL for a subfolder
Inputs: subfolder (required), database, limit.
semrush_subfolder_rankCRead-onlyIdempotent
Get ranking data for a subfolder in a specific database
Inputs: subfolder (required), database, limit.
semrush_subfolder_rank_historyBRead-onlyIdempotent
Get historical ranking data for a subfolder
Inputs: subfolder (required), database, limit.
semrush_subfolder_ranksCRead-onlyIdempotent
Get ranking data for a subfolder across all databases
Inputs: subfolder (required), limit.
semrush_traffic_accuracyBRead-onlyIdempotent
Get data accuracy score for traffic analytics (requires .Trends)
Inputs: target (required), display_date, limit.
semrush_traffic_destinationsBRead-onlyIdempotent
Get outbound traffic destinations for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_traffic_geoCRead-onlyIdempotent
Get geographic distribution of traffic for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_traffic_rankCRead-onlyIdempotent
Get traffic rank for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_traffic_social_mediaCRead-onlyIdempotent
Get social media traffic distribution for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_traffic_sourcesBRead-onlyIdempotent
Get traffic sources data for a domain (requires .Trends API access)
Inputs: domain (required), country.
semrush_traffic_subdomainsCRead-onlyIdempotent
Get subdomain traffic distribution for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_traffic_subfoldersCRead-onlyIdempotent
Get subfolder traffic distribution for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_traffic_summaryCRead-onlyIdempotent
Get traffic summary data for domains (requires .Trends API access)
Inputs: domains (required), country.
semrush_traffic_top_pagesCRead-onlyIdempotent
Get top pages by traffic for a domain (requires .Trends)
Inputs: target (required), country, device_type, display_date, +1 more.
semrush_update_projectA
Update a Semrush project name
Inputs: project_id (required), project_name (required).
semrush_url_adwordsBRead-onlyIdempotent
Get paid keywords for a specific URL
Inputs: url (required), database, limit.
semrush_url_organicBRead-onlyIdempotent
Get organic keywords for a specific URL
Inputs: url (required), database, limit.
semrush_url_rankCRead-onlyIdempotent
Get ranking data for a specific URL
Inputs: url (required), database, limit.
semrush_url_rank_historyCRead-onlyIdempotent
Get historical ranking data for a specific URL
Inputs: url (required), database, limit.
semrush_url_ranksCRead-onlyIdempotent
Get ranking data for a URL across all databases
Inputs: url (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 77 tools
Each tool targets a specific entity and data type (e.g., domain organic keywords vs subdomain organic keywords vs URL organic keywords), with descriptions clarifying the exact scope. Some overlap exists between overview and specific tools, but overall distinct.
All tools follow a strict 'semrush_{entity}_{detail}' snake_case pattern (e.g., semrush_backlinks_anchors, semrush_domain_organic_keywords). No mixed conventions or irregular naming.
With 77 tools, the server is overly granular for a typical MCP interface. While covering a broad domain, the high count can overwhelm agents and make tool selection error-prone, contrary to MCP best practices.
The tool set comprehensively covers Semrush's core offerings: keywords, backlinks, traffic, audience, site audits, and project management at multiple levels (domain, subdomain, subfolder, URL). No obvious functional gaps.
Maintenance
Related MCP Connectors
Semrush MCP Pack — SEO analytics via the Semrush Analytics API.
SEO MCP server for keyword research, live SERPs, backlinks, site audits and AI visibility.
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
SEO MCP server for keyword research, SERP analysis, audits, and Search Console workflows.
Related MCP Servers
- AlicenseBqualityDmaintenanceA MCP server for retrieving backlink information for any domain(SEO).4445 PyPI260MIT
- AlicenseBqualityDmaintenanceMCP server providing tools to access Semrush API data for domain analytics, keyword research, backlink analysis, and traffic analytics.1973 npmMIT
- AlicenseCqualityDmaintenanceMCP server for Keys.so SEO API, enabling domain and keyword analysis, competitor research, and SEO metrics retrieval through natural language.1514ISC
- AlicenseCqualityCmaintenanceOpen-source MCP server for Bisibility, providing tools for keyword rank tracking, SERP history, keyword research, backlinks, alerts, reports, and project management. Runs locally through npm or Docker and connects to Bisibility Cloud or a self-hosted instance.140353 npm3Apache 2.0