Skip to content

mrkooblu/semrush-mcp

BranchesTags

Repository files navigation

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

About

A Model Context Protocol (MCP) server implementation that provides tools for accessing Semrush API data.

Resources

Readme

License

MIT license
Activity

Stars

34 stars

Watchers

1 watching

Forks

11 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages