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:

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:

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)

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

Requires `SEMRUSH_API_KEY` in environment or `.env` file.

API Units Consumption

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

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