springvoiceswell/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

• 🔍 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

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

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

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

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

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.

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

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

1. Verify everything works:

npx semrush-ai-tool units

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

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

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.

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

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.

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

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

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

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

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.

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

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

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.

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

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

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

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.

MIT © 2026 springvoiceswell — free for personal and commercial use.