🚀 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.

⚡ Quick Install · 🤖 Connect Your AI · ⌨️ CLI Usage · 🧰 All 18 Tools · 👩‍💻 Developers

🎯 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:

✅ 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

Related MCP server: Semrush MCP Server

✨ 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 — copy & paste, no experience needed

• 👩‍💻 I'm a developer → jump to the quick install

🍎 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:

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:

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:

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)

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 below.

👩‍💻 Quick Install (Developers)

Requires Node.js 18+.

# 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 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:

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

3. Verify everything works:

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):

{
  "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.

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

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

🧰 Available MCP Tools

🌐 Domain Analytics

🔍 Keyword Research

🔗 Backlink Analysis

📈 Traffic & 💳 Utility

💰 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

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

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:

npx @modelcontextprotocol/inspector node src/index.js

⚙️ Configuration

➕ Adding a New Tool

1. Find the report type in the Semrush API docs.

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 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 © 2026 springvoiceswell — free for personal and commercial use.

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