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

bash

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:

bash

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):

json

{
  "mcpServers": {
    "semrush-mcp": {
      "command": "npx",
      "args": ["-y", "github:mrkooblu/semrush-mcp"],
      "env": {
        "SEMRUSH_API_KEY": "your-api-key"
      }
    }
  }
}

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

bash

npm install -g github:mrkooblu/semrush-mcp

Or clone and link locally

bash

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:

bash

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):

json

{
  "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 (country code, default: us), -l, --limit , and -f, --format .

Quick Overview

Auto-detects keyword vs domain:

bash

semrush q "seo tools"              # Keyword overview
semrush q example.com              # Domain overview

Domain Analytics

bash

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

bash

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

bash

semrush kd "seo" "content marketing" "link building"

Backlinks

bash

semrush bl example.com                        # Backlink overview
semrush bl example.com --domains -l 20        # Referring domains

Traffic Analytics

Requires .Trends API subscription.

bash

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

Keyword Gap Analysis

bash

semrush gaps mysite.com competitor.com -l 50

API Units Balance

bash

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

Backlinks (7 tools)

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

Traffic & Audience (17 tools, requires .Trends subscription)

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`	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

bash

git clone https://github.com/mrkooblu/semrush-mcp.git
cd semrush-mcp
npm install
cp .env.example .env   # add your SEMRUSH_API_KEY

bash

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

Semrush Mcp

Documentation

Semrush MCP

Quick Start

Features

Installation

Install globally from GitHub

Or clone and link locally

MCP Setup

Claude Desktop

Cursor

Other MCP Clients

CLI Usage

Quick Overview

Domain Analytics

Keyword Research

Keyword Difficulty

Backlinks

Traffic Analytics

Keyword Gap Analysis

API Units Balance

Available MCP Tools

Domain Analytics (13 tools)

URL Analytics (5 tools)

Subdomain Analytics (4 tools)

Subfolder Analytics (7 tools)

Backlinks (7 tools)

Keyword Research (10 tools)

Traffic & Audience (17 tools, requires .Trends subscription)

Projects & Site Audit (13 tools)

Utility (1 tool)

CLI-Only Commands

Configuration

API Units Consumption

Development

Git Hooks

Why Self-Host?

Security

Hosted Alternative

License

Similar MCP

Waha Mcp

Wizzy Mcp Tmdb

Rijksmuseum Mcp

Mcp Server Playwright

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Waha Mcp

Wizzy Mcp Tmdb

Rijksmuseum Mcp

Mcp Server Playwright

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare