Skip to main content
Glama
Semrush MCP
by mrkooblu

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_here

After installing, you have two commands:

  • semrush — CLI for terminal and agent use

  • semrush-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 analysis

MCP 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-mcp
git clone https://github.com/mrkooblu/semrush-mcp.git
cd semrush-mcp
npm install && npm run build && npm link

Set your API key in the environment or a .env file:

export SEMRUSH_API_KEY=your_api_key_here

MCP 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

  1. Go to Settings > MCP Servers > Add Server

  2. Configure:

    • Name: Semrush MCP

    • Type: command

    • Command: node

    • Arguments: /path/to/semrush-mcp/dist/index.js

    • Environment 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 overview

Domain 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     # Competitors

Keyword 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 results

Keyword Difficulty

semrush kd "seo" "content marketing" "link building"
semrush bl example.com                        # Backlink overview
semrush bl example.com --domains -l 20        # Referring domains

Traffic Analytics

Requires .Trends API subscription.

semrush traffic example.com                   # Traffic summary
semrush traffic example.com --sources         # Traffic sources

Keyword Gap Analysis

semrush gaps mysite.com competitor.com -l 50

API Units Balance

semrush units

Available MCP Tools

Domain Analytics (13 tools)

Tool

Description

semrush_domain_overview

Domain overview — traffic, keywords, rankings across all databases

semrush_domain_rank

Domain rank in a specific database

semrush_domain_rank_history

Historical rank data for a domain

semrush_rank_difference

Domains with biggest rank changes

semrush_domain_organic_keywords

Organic keywords for a domain

semrush_domain_paid_keywords

Paid keywords for a domain

semrush_competitors

Organic search competitors

semrush_paid_competitors

Paid search competitors

semrush_domain_ads_history

Domain's ad history over time

semrush_domain_organic_unique

Unique organic pages for a domain

semrush_domain_adwords_unique

Unique paid ad pages for a domain

semrush_domain_shopping

Shopping/PLA keywords for a domain

semrush_domain_shopping_unique

Unique shopping ad pages

URL Analytics (5 tools)

Tool

Description

semrush_url_organic

Organic keywords for a specific URL

semrush_url_adwords

Paid keywords for a specific URL

semrush_url_rank

Rank data for a specific URL

semrush_url_rank_history

Historical rank data for a URL

semrush_url_ranks

Rank across all databases for a URL

Subdomain Analytics (4 tools)

Tool

Description

semrush_subdomain_rank

Rank data for a subdomain

semrush_subdomain_ranks

Rank across all databases for a subdomain

semrush_subdomain_rank_history

Historical rank data for a subdomain

semrush_subdomain_organic

Organic keywords for a subdomain

Subfolder Analytics (7 tools)

Tool

Description

semrush_subfolder_organic

Organic keywords for a subfolder

semrush_subfolder_adwords

Paid keywords for a subfolder

semrush_subfolder_rank

Rank data for a subfolder

semrush_subfolder_ranks

Rank across all databases for a subfolder

semrush_subfolder_rank_history

Historical rank data for a subfolder

semrush_subfolder_organic_unique

Unique organic pages in a subfolder

semrush_subfolder_adwords_unique

Unique paid ad pages in a subfolder

Tool

Description

semrush_backlinks

Backlinks for a domain/URL

semrush_backlinks_domains

Referring domains

semrush_backlinks_overview

Backlinks summary stats

semrush_backlinks_pages

Pages with most backlinks

semrush_backlinks_anchors

Anchor text distribution

semrush_backlinks_tld

TLD distribution of backlinks

semrush_backlinks_categories

Category distribution of backlinks

Keyword Research (10 tools)

Tool

Description

semrush_keyword_overview

Keyword overview across all databases

semrush_keyword_overview_single_db

Detailed keyword data for specific database

semrush_batch_keyword_overview

Analyze up to 100 keywords at once

semrush_related_keywords

Related keyword discovery

semrush_broad_match_keywords

Broad match / alternate queries

semrush_phrase_questions

Question-based keywords

semrush_keyword_organic_results

Domains ranking in organic results

semrush_keyword_paid_results

Domains in paid search results

semrush_keyword_ads_history

12-month history of domains bidding on a keyword

semrush_keyword_difficulty

Difficulty index for ranking in top 10

Tool

Description

semrush_traffic_summary

Traffic summary for domains

semrush_traffic_sources

Traffic sources breakdown

semrush_traffic_destinations

Where traffic goes after visiting

semrush_traffic_geo

Geographic distribution of traffic

semrush_traffic_subdomains

Traffic by subdomain

semrush_traffic_subfolders

Traffic by subfolder

semrush_traffic_top_pages

Highest-traffic pages

semrush_traffic_rank

Traffic rank over time

semrush_traffic_social_media

Social media traffic breakdown

semrush_audience_insights

Audience overlap between domains

semrush_purchase_conversion

Purchase conversion metrics

semrush_household_distribution

Household size demographics

semrush_income_distribution

Income demographics

semrush_education_distribution

Education level demographics

semrush_occupation_distribution

Occupation demographics

semrush_audience_interests

Audience interest categories

semrush_traffic_accuracy

Traffic data accuracy estimates

Projects & Site Audit (13 tools)

Tool

Description

semrush_list_projects

List all projects

semrush_get_project

Get project details

semrush_create_project

Create a new project

semrush_update_project

Update project settings

semrush_delete_project

Delete a project

semrush_site_audit_info

Site audit configuration and status

semrush_site_audit_snapshots

List audit snapshots

semrush_site_audit_snapshot_detail

Get snapshot details

semrush_site_audit_issues

Audit issue metadata

semrush_site_audit_pages

List audited pages

semrush_site_audit_page_detail

Page-level audit details

semrush_site_audit_history

Audit history

semrush_site_audit_launch

Launch a new audit crawl

Utility (1 tool)

Tool

Description

semrush_api_units_balance

Check API units balance

CLI-Only Commands

CLI Command

Description

semrush gaps <d1> <d2>

Keyword gap analysis between two domains

Configuration

Requires SEMRUSH_API_KEY in environment or .env file.

Variable

Default

Description

SEMRUSH_API_KEY

(required)

Your Semrush API key

API_CACHE_TTL_SECONDS

300

Cache TTL for API responses

API_RATE_LIMIT_PER_SECOND

10

Maximum API requests per second

NODE_ENV

development

Environment mode

LOG_LEVEL

info

Logging level

API Units Consumption

API requests consume units from your Semrush account. Different reports have different costs:

Tool

API Units per Line

semrush_keyword_overview

10

semrush_keyword_overview_single_db

10

semrush_batch_keyword_overview

10

semrush_keyword_organic_results

10

semrush_keyword_paid_results

20

semrush_broad_match_keywords

20

semrush_related_keywords

40

semrush_phrase_questions

40

semrush_keyword_difficulty

50

semrush_keyword_ads_history

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_KEY
npm 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           # Prettier

Git 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 semrush directly without MCP

  • Open 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

MIT

Available Tools

77 tools
semrush_api_units_balanceA
Read-onlyIdempotent

Check the remaining API units balance

Inputs: no named parameters.

semrush_audience_insightsC
Read-onlyIdempotent

Get audience overlap and similarity data between domains (requires .Trends)

Inputs: targets (required), selected_targets (required), limit.

semrush_audience_interestsC
Read-onlyIdempotent

Get audience interest categories for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_batch_keyword_overviewA
Read-onlyIdempotent

Analyze up to 100 keywords at once in a specific database (10 API units per line)

Inputs: keywords (required), database.

semrush_broad_match_keywordsB
Read-onlyIdempotent

Get broad matches and alternate search queries for a keyword (20 API units per line)

Inputs: keyword (required), database (required), limit.

semrush_competitorsB
Read-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_projectC
Destructive

Delete a Semrush project

Inputs: project_id (required).

semrush_domain_ads_historyC
Read-onlyIdempotent

Get ads history for a domain over last 12 months

Inputs: domain (required), database, limit.

semrush_domain_adwords_uniqueC
Read-onlyIdempotent

Get unique paid ads for a domain

Inputs: domain (required), database, limit.

semrush_domain_organic_keywordsC
Read-onlyIdempotent

Get organic keywords for a specific domain

Inputs: domain (required), database, limit.

semrush_domain_organic_uniqueB
Read-onlyIdempotent

Get unique organic keywords grouped by URL for a domain

Inputs: domain (required), database, limit.

semrush_domain_overviewC
Read-onlyIdempotent

Get domain overview data including organic/paid search traffic, keywords, and rankings

Inputs: domain (required), database, limit.

semrush_domain_paid_keywordsC
Read-onlyIdempotent

Get paid keywords for a specific domain

Inputs: domain (required), database, limit.

semrush_domain_rankC
Read-onlyIdempotent

Get domain ranking in a specific database

Inputs: domain (required), database, limit.

semrush_domain_rank_historyC
Read-onlyIdempotent

Get historical ranking data for a domain

Inputs: domain (required), database, limit.

semrush_domain_shoppingC
Read-onlyIdempotent

Get PLA (Product Listing Ads) search keywords for a domain

Inputs: domain (required), database, limit.

semrush_domain_shopping_uniqueC
Read-onlyIdempotent

Get unique shopping ads for a domain

Inputs: domain (required), database, limit.

semrush_education_distributionB
Read-onlyIdempotent

Get education level distribution of audience (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_get_projectC
Read-onlyIdempotent

Get details of a specific Semrush project

Inputs: project_id (required).

semrush_household_distributionC
Read-onlyIdempotent

Get household size distribution of audience (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_income_distributionC
Read-onlyIdempotent

Get income distribution of audience (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_keyword_ads_historyB
Read-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_difficultyA
Read-onlyIdempotent

Get difficulty index for ranking in Google's top 10 (50 API units per line)

Inputs: keywords (required), database.

semrush_keyword_organic_resultsB
Read-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_overviewC
Read-onlyIdempotent

Get overview data for a specific keyword

Inputs: keyword (required), database, limit.

semrush_keyword_overview_single_dbC
Read-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_resultsC
Read-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_projectsA
Read-onlyIdempotent

List all Semrush projects

Inputs: no named parameters.

semrush_occupation_distributionC
Read-onlyIdempotent

Get occupation distribution of audience (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_paid_competitorsB
Read-onlyIdempotent

Get paid search competitors for a domain

Inputs: domain (required), database, limit.

semrush_phrase_questionsC
Read-onlyIdempotent

Get question-based keywords related to a term (40 API units per line)

Inputs: keyword (required), database (required), limit.

semrush_purchase_conversionA
Read-onlyIdempotent

Get purchase conversion rate for a domain (requires .Trends, desktop only)

Inputs: target (required), country, display_date, limit.

semrush_rank_differenceC
Read-onlyIdempotent

Get winners and losers — domains with biggest ranking changes

Inputs: database, limit.

semrush_site_audit_historyC
Read-onlyIdempotent

Get site audit crawl history

Inputs: project_id (required), limit, offset.

semrush_site_audit_infoC
Read-onlyIdempotent

Get site audit information for a project

Inputs: project_id (required).

semrush_site_audit_issuesC
Read-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_detailB
Read-onlyIdempotent

Get detailed audit data for a specific page

Inputs: project_id (required), page_id (required).

semrush_site_audit_pagesC
Read-onlyIdempotent

List pages from a site audit

Inputs: project_id (required), url (required), limit, page.

semrush_site_audit_snapshot_detailC
Read-onlyIdempotent

Get detailed site audit snapshot data

Inputs: project_id (required), snapshot_id (required).

semrush_site_audit_snapshotsC
Read-onlyIdempotent

List site audit snapshots for a project

Inputs: project_id (required).

semrush_subdomain_organicC
Read-onlyIdempotent

Get organic keywords for a subdomain

Inputs: subdomain (required), database, limit.

semrush_subdomain_rankC
Read-onlyIdempotent

Get ranking data for a subdomain in a specific database

Inputs: subdomain (required), database, limit.

semrush_subdomain_rank_historyB
Read-onlyIdempotent

Get historical ranking data for a subdomain

Inputs: subdomain (required), database, limit.

semrush_subdomain_ranksB
Read-onlyIdempotent

Get ranking data for a subdomain across all databases

Inputs: subdomain (required), limit.

semrush_subfolder_adwordsC
Read-onlyIdempotent

Get paid keywords for a subfolder

Inputs: subfolder (required), database, limit.

semrush_subfolder_adwords_uniqueC
Read-onlyIdempotent

Get unique paid ads for a subfolder

Inputs: subfolder (required), database, limit.

semrush_subfolder_organicB
Read-onlyIdempotent

Get organic keywords for a subfolder (e.g. domain.com/blog/)

Inputs: subfolder (required), database, limit.

semrush_subfolder_organic_uniqueB
Read-onlyIdempotent

Get unique organic keywords grouped by URL for a subfolder

Inputs: subfolder (required), database, limit.

semrush_subfolder_rankC
Read-onlyIdempotent

Get ranking data for a subfolder in a specific database

Inputs: subfolder (required), database, limit.

semrush_subfolder_rank_historyB
Read-onlyIdempotent

Get historical ranking data for a subfolder

Inputs: subfolder (required), database, limit.

semrush_subfolder_ranksC
Read-onlyIdempotent

Get ranking data for a subfolder across all databases

Inputs: subfolder (required), limit.

semrush_traffic_accuracyB
Read-onlyIdempotent

Get data accuracy score for traffic analytics (requires .Trends)

Inputs: target (required), display_date, limit.

semrush_traffic_destinationsB
Read-onlyIdempotent

Get outbound traffic destinations for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_traffic_geoC
Read-onlyIdempotent

Get geographic distribution of traffic for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_traffic_rankC
Read-onlyIdempotent

Get traffic rank for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_traffic_social_mediaC
Read-onlyIdempotent

Get social media traffic distribution for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_traffic_sourcesB
Read-onlyIdempotent

Get traffic sources data for a domain (requires .Trends API access)

Inputs: domain (required), country.

semrush_traffic_subdomainsC
Read-onlyIdempotent

Get subdomain traffic distribution for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_traffic_subfoldersC
Read-onlyIdempotent

Get subfolder traffic distribution for a domain (requires .Trends)

Inputs: target (required), country, device_type, display_date, +1 more.

semrush_traffic_summaryC
Read-onlyIdempotent

Get traffic summary data for domains (requires .Trends API access)

Inputs: domains (required), country.

semrush_traffic_top_pagesC
Read-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_adwordsB
Read-onlyIdempotent

Get paid keywords for a specific URL

Inputs: url (required), database, limit.

semrush_url_organicB
Read-onlyIdempotent

Get organic keywords for a specific URL

Inputs: url (required), database, limit.

semrush_url_rankC
Read-onlyIdempotent

Get ranking data for a specific URL

Inputs: url (required), database, limit.

semrush_url_rank_historyC
Read-onlyIdempotent

Get historical ranking data for a specific URL

Inputs: url (required), database, limit.

semrush_url_ranksC
Read-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

    B3/5.0

    Scored across 77 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A MCP server for retrieving backlink information for any domain(SEO).
      4
      4
      45 PyPI
      260
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server providing tools to access Semrush API data for domain analytics, keyword research, backlink analysis, and traffic analytics.
      19
      73 npm
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      MCP server for Keys.so SEO API, enabling domain and keyword analysis, competitor research, and SEO metrics retrieval through natural language.
      151
      4
      ISC
    • A
      license
      C
      quality
      C
      maintenance
      Open-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.
      140
      353 npm
      3
      Apache 2.0