<div align="center">

# 🚀 semrush-ai-tool

### AI-Powered Semrush SEO Analysis — MCP Server & CLI for Keyword Research, Backlinks & Competitor Intelligence

**Turn any AI assistant into a professional SEO analyst.** Connect Claude, Cursor, or any MCP-compatible AI client directly to live Semrush data — keyword research, domain analytics, backlink analysis, traffic insights, and competitor intelligence — with a single install.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/en/download)
[![MCP](https://img.shields.io/badge/Protocol-MCP-blue)](https://modelcontextprotocol.io)
[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#-installation)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#-contributing)

[⚡ Quick Install](#-installation) · [🤖 Connect Your AI](#-connect-your-ai-assistant-mcp-setup) · [⌨️ CLI Usage](#%EF%B8%8F-cli-usage) · [🧰 All 18 Tools](#-available-mcp-tools) · [👩‍💻 Developers](#-developer-guide)

</div>

---

## 🎯 What is semrush-ai-tool?

**semrush-ai-tool** is a free, open-source **Semrush SEO analysis tool** that gives AI assistants real-time access to the **Semrush API** through the **Model Context Protocol (MCP)** — the open standard for connecting AI models to external data.

Instead of exporting CSVs and pasting them into a chat window, you simply ask your AI:

> *"Analyze the top organic keywords for mysite.com, compare them with competitor.com, score the keyword difficulty, and tell me which backlinks I'm missing."*

The AI calls the Semrush API for you, reads the results, and delivers a complete **SEO analysis** — keyword gaps, backlink opportunities, traffic trends, and competitor strategy — in plain English.

It ships as **two tools in one package**:

| Entry point | Who it's for | What it does |
|---|---|---|
| 🤖 **MCP Server** (`semrush-ai-mcp`) | Marketers, SEOs, founders | Gives Claude Desktop, Cursor & other AI clients **18 Semrush tools** |
| ⌨️ **CLI** (`semrush-ai`) | Developers, power users, AI coding agents | Run Semrush reports straight from the terminal |

✅ **No build step** — pure JavaScript, installs in seconds
✅ **No Homebrew required** — works with a standard Node.js setup
✅ **Self-hosted & private** — your API key never leaves your machine
✅ **MIT licensed** — free for personal and commercial use

---

## ✨ Features

- **🔍 Keyword Research** — search volume, CPC, competition, trends, related keywords, question keywords (People Also Ask gold), and batch **Keyword Difficulty** scoring for up to 100 keywords at once
- **🌐 Domain Analytics** — organic & paid keywords, traffic estimates, rank history, and visibility for any domain in any regional database (US, UK, DE, FR, and 100+ more)
- **🕵️ Competitor Analysis** — discover organic and paid competitors, reverse-engineer their keyword portfolios, and find the gaps in yours
- **🔗 Backlink Analysis** — backlink profile overviews, individual backlinks with anchors, and referring domains sorted by authority for link-building prospecting
- **📈 Traffic Analytics** — visits, unique visitors, bounce rate, and session duration via Semrush .Trends
- **📊 SERP Snapshots** — see exactly which domains and URLs rank for any keyword
- **💳 API Units Tracking** — check your Semrush API units balance before big jobs
- **⚡ Built-in rate limiting** — never trip Semrush's API limits
- **🧩 Works everywhere MCP works** — Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client

---

## ⚡ Installation

Choose your path:

- **🍎 I'm not a developer** → follow the [step-by-step macOS guide](#-macos-installation-for-non-developers-step-by-step) — copy & paste, no experience needed
- **👩‍💻 I'm a developer** → jump to the [quick install](#-quick-install-developers)

### 🍎 macOS Installation for Non-Developers (Step by Step)

No Homebrew. No programming knowledge. Just open **Terminal** (press `Cmd + Space`, type `Terminal`, hit Enter) and follow these three steps.

#### Step 1 — Install Apple's command line tools

Copy, paste, and press Enter:

```bash
xcode-select --install
```

A dialog pops up → click **Install** and wait for it to finish. (If it says they're already installed, great — move on.)

#### Step 2 — Install Node.js with nvm

Node.js is the engine this tool runs on, and **nvm** is the official, recommended way to install it — no Homebrew needed. Copy and paste this one line:

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
```

Then **close Terminal completely and open it again** (this loads nvm). Now install Node.js:

```bash
nvm install --lts
```

✅ **Check it worked:** type `node -v` — you should see something like `v22.x.x`.

> 💡 This is the same method shown on the official Node.js download page: <https://nodejs.org/en/download>

#### Step 3 — Install semrush-ai-tool (one line)

```bash
mkdir -p 'semrushai' && cd 'semrushai' && npm install github:springvoiceswell/semrush-ai-tool
```

Done! 🎉 The tool now lives in a folder called `semrushai` in your home directory. Continue to [Get your API key](#-get-your-semrush-api-key) below.

### 👩‍💻 Quick Install (Developers)

Requires **Node.js 18+**.

```bash
# Local project install
mkdir -p 'semrushai' && cd 'semrushai' && npm install github:springvoiceswell/semrush-ai-tool

# …or global install for the CLI everywhere
npm install -g github:springvoiceswell/semrush-ai-tool

# …or clone for hacking
git clone https://github.com/springvoiceswell/semrush-ai-tool.git
cd semrush-ai-tool && npm install
```

### 🔑 Get Your Semrush API Key

1. Log in to Semrush and open **Account → [API](https://www.semrush.com/accounts/profile/)** to find your API key. *(API access requires a Semrush Business subscription or purchased API units.)*
2. Tell your Mac about it — paste this into Terminal, replacing the placeholder with your real key:

```bash
echo 'export SEMRUSH_API_KEY="paste_your_key_here"' >> ~/.zshrc && source ~/.zshrc
```

3. Verify everything works:

```bash
npx semrush-ai-tool units
```

If you see your API units balance — you're fully set up. 🎉

---

## 🤖 Connect Your AI Assistant (MCP Setup)

This is where the magic happens: your AI gets 18 live Semrush tools.

### Claude Desktop

Open (or create) this file:

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

> **Non-developers:** in Finder press `Cmd + Shift + G`, paste the path above, and open the file with TextEdit. If it doesn't exist, create it.

Paste this in (replace the key with yours):

```json
{
  "mcpServers": {
    "semrush-ai-tool": {
      "command": "npx",
      "args": ["-y", "github:springvoiceswell/semrush-ai-tool"],
      "env": {
        "SEMRUSH_API_KEY": "paste_your_key_here"
      }
    }
  }
}
```

**Restart Claude Desktop.** You should see 🔨 tools available — Claude can now run live Semrush SEO analysis.

### Cursor

1. **Settings → MCP → Add new global MCP server**
2. Use the same JSON block as above, or:
   - **Type:** `command`
   - **Command:** `npx -y github:springvoiceswell/semrush-ai-tool`
   - **Environment:** `SEMRUSH_API_KEY=your_key`

### Other MCP Clients (Windsurf, Cline, etc.)

Any MCP-compatible client can connect over stdio. Point it at:

```
npx -y github:springvoiceswell/semrush-ai-tool
```

with the `SEMRUSH_API_KEY` environment variable set.

### 💬 What to Ask Your AI

Once connected, just talk naturally:

- *"Give me a full SEO overview of example.com — traffic, top keywords, and how rankings changed over the last year."*
- *"Find 20 low-difficulty question keywords related to 'email marketing' I could rank for."*
- *"Who are the top organic competitors of mysite.com and what keywords do we share?"*
- *"Audit the backlink profile of example.com and list the strongest referring domains."*
- *"Score the keyword difficulty of these 10 keywords and tell me which to target first."*

---

## ⌨️ CLI Usage

The `semrush-ai` CLI is built for humans **and** AI coding agents (Claude Code, etc.) that can run shell commands.

```bash
semrush-ai q "seo tools"                 # 🔮 Smart lookup — auto-detects keyword vs domain
semrush-ai domain example.com            # 🌐 Domain overview
semrush-ai domain example.com --organic -l 30      # Top 30 organic keywords
semrush-ai domain example.com --competitors        # Organic competitors
semrush-ai domain example.com --history            # Rank history
semrush-ai kw "content marketing"                  # Keyword overview
semrush-ai kw "seo" --related -l 20                # Related keywords
semrush-ai kw "marketing" --questions -l 10        # Question keywords
semrush-ai kw "seo tools" --serp                   # Who ranks on the SERP
semrush-ai kd "seo" "link building" "ppc"          # Keyword Difficulty batch
semrush-ai bl example.com                          # Backlink overview
semrush-ai bl example.com --domains -l 20          # Top referring domains
semrush-ai traffic example.com                     # Traffic summary (.Trends)
semrush-ai units                                   # API units balance
```

**Global flags:** `-d, --database <code>` (default `us`) · `-l, --limit <n>` · `-f, --format text|json`

```bash
semrush-ai domain example.com --organic -d uk -l 50 -f json
```

---

## 🧰 Available MCP Tools

### 🌐 Domain Analytics

| Tool | Description |
|---|---|
| `semrush_domain_overview` | Domain overview across all databases — traffic, keywords, Semrush rank |
| `semrush_domain_rank` | Organic & paid visibility in one regional database |
| `semrush_domain_rank_history` | Monthly historical rankings, keywords and traffic |
| `semrush_domain_organic_keywords` | Keywords the domain ranks for in Google's top 100 |
| `semrush_domain_paid_keywords` | Keywords the domain bids on in Google Ads |
| `semrush_domain_competitors` | Organic search competitors with competition level |
| `semrush_domain_paid_competitors` | Paid search (Google Ads) competitors |

### 🔍 Keyword Research

| Tool | Description |
|---|---|
| `semrush_keyword_overview` | Volume, CPC & competition across all databases |
| `semrush_keyword_overview_single_db` | Detailed metrics + trends in one database |
| `semrush_related_keywords` | Related phrases & variations for content ideation |
| `semrush_keyword_questions` | Question keywords for FAQs & featured snippets |
| `semrush_keyword_difficulty` | Difficulty index (0–100), up to 100 keywords per call |
| `semrush_keyword_serp` | Domains & URLs ranking organically for a keyword |

### 🔗 Backlink Analysis

| Tool | Description |
|---|---|
| `semrush_backlinks_overview` | Backlinks, referring domains, IPs, follow/nofollow |
| `semrush_backlinks` | Individual backlinks with anchors & first/last seen |
| `semrush_backlinks_refdomains` | Referring domains sorted by authority |

### 📈 Traffic & 💳 Utility

| Tool | Description |
|---|---|
| `semrush_traffic_summary` | Visits, uniques, bounce rate, duration *(requires .Trends)* |
| `semrush_api_units_balance` | Remaining Semrush API units |

> 💰 **API units:** every Semrush API call consumes units from your account. Run `semrush-ai units` (or ask your AI) to check your balance before large batch jobs.

---

## 👩‍💻 Developer Guide

This section is for contributors and engineers who want to understand, extend, or embed **semrush-ai-tool**.

### 🏗️ Architecture

Deliberately minimal — zero build step, two runtime dependencies, plain ESM JavaScript:

```
semrush-ai-tool/
├── src/
│   ├── index.js    # MCP server entry (stdio transport, @modelcontextprotocol/sdk)
│   ├── cli.js      # CLI entry — dependency-free arg parsing, text/JSON output
│   ├── api.js      # SemrushClient: Analytics + Backlinks + .Trends APIs,
│   │               #   token-bucket rate limiter, CSV parser, typed errors
│   └── tools.js    # 18 MCP tool definitions (zod schemas → Semrush reports)
├── tests/          # node:test unit tests (no API key required)
├── .env.example
└── package.json
```

**Design decisions:**

- **No transpilation.** The package runs as-shipped on Node 18+, so `npm install github:...` works instantly with no `prepare`/`build` surprises — critical for non-developer installs.
- **Thin tool layer.** Each MCP tool maps 1:1 to a Semrush API report. Adding a tool = one `server.registerTool()` call with a zod schema. PRs that add reports are trivial to review.
- **Errors that explain themselves.** Semrush returns logical errors as `ERROR <code>` with HTTP 200; the client normalizes these into actionable messages (check key / subscription / units).
- **stdout is sacred.** The MCP server never writes to stdout except protocol frames — all logs go to stderr.

### 🔧 Local Development

```bash
git clone https://github.com/springvoiceswell/semrush-ai-tool.git
cd semrush-ai-tool
npm install
cp .env.example .env   # add your SEMRUSH_API_KEY
```

```bash
npm test                    # Unit tests (no API key needed)
npm start                   # Run the MCP server on stdio
npm run cli -- units        # Run the CLI
node --inspect src/index.js # Debug the server
```

**Test the MCP server end-to-end** with the official inspector:

```bash
npx @modelcontextprotocol/inspector node src/index.js
```

### ⚙️ Configuration

| Variable | Default | Description |
|---|---|---|
| `SEMRUSH_API_KEY` | *(required)* | Your Semrush API key |
| `SEMRUSH_RATE_LIMIT_PER_SECOND` | `10` | Max API requests per second |
| `SEMRUSH_TIMEOUT_MS` | `30000` | Per-request timeout |

### ➕ Adding a New Tool

1. Find the report type in the [Semrush API docs](https://developer.semrush.com/api/).
2. Add a `server.registerTool()` block in `src/tools.js` with a zod input schema.
3. Add the tool name to `TOOL_NAMES` and to the README table.
4. Run `npm test` and open a PR. 🎉

### 🤝 Contributing

Contributions are welcome — new Semrush reports, CLI commands, docs, tests, and bug fixes.

1. Fork the repo and create a feature branch: `git checkout -b feat/my-report`
2. Keep the zero-build-step constraint (plain ESM JS, Node 18+).
3. Add/adjust tests: `npm test` must pass.
4. Open a PR with a clear description of the Semrush report or behavior added.

Please open an [issue](https://github.com/springvoiceswell/semrush-ai-tool/issues) first for large changes.

---

## 🔒 Security

- **Never commit your API key.** `.env` is git-ignored; use environment variables or your MCP client's `env` block.
- Your key is sent only to Semrush's official API endpoints over HTTPS — this tool is fully self-hosted and makes no other network calls.
- Anyone with your key can spend your API units. Rotate it immediately if exposed.

## ❓ FAQ

**Do I need a paid Semrush account?**
Yes — the Semrush API requires a Business subscription or purchased API units. The tool itself is free and open source.

**Is this an official Semrush product?**
No. This is a community-built, open-source project and is not affiliated with or endorsed by Semrush. Semrush also offers an official hosted MCP connector at `https://mcp.semrush.com/v1/mcp` if you prefer a managed option.

**Does it work on Windows/Linux?**
Yes — anywhere Node.js 18+ runs. The step-by-step guide above is macOS-specific, but developers on any OS can use the quick install.

**The AI says the tool failed with an API error?**
Run `semrush-ai units` — most failures are an unset `SEMRUSH_API_KEY`, an exhausted units balance, or a report your subscription doesn't include (e.g. .Trends).

## 🗺️ Roadmap

- [ ] Keyword Gap analysis (domain-vs-domain)
- [ ] Site Audit & Projects API tools
- [ ] Full .Trends traffic & audience suite
- [ ] Cached responses with configurable TTL
- [ ] npm registry release (`npm i semrush-ai-tool`)

## ⭐ Support the Project

If **semrush-ai-tool** saves you time, please **star the repo** — it helps other SEOs and developers find it. Shares, issues, and PRs are all appreciated.

## 📄 License

[MIT](LICENSE) © 2026 springvoiceswell — free for personal and commercial use.

---

<div align="center">

**Keywords:** Semrush SEO tool · Semrush API · MCP server · Model Context Protocol · AI SEO analysis · keyword research tool · backlink analysis · competitor analysis · domain analytics · keyword difficulty · SERP analysis · SEO automation · Claude SEO · Cursor MCP · AI marketing tools

</div>