Content
# 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 <db>` (country code, default: `us`), `-l, --limit <n>`, and `-f, --format <text|json>`.
### 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 <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
```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](https://typicode.github.io/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](https://www.semrush.com/kb/1618-mcp) at `https://mcp.semrush.com/v1/mcp` — no setup required, authenticate with your Semrush account. See [Getting Started with MCP](https://www.semrush.com/kb/1619-getting-started-with-mcp) for details.
This is a personal project and not an official Semrush product.
## License
[MIT](./LICENSE)
