Semrush MCP Server

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