Semrush MCP Server

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"
      }
    }
  }
}

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

Or clone and link locally

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"

Backlinks

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

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