Semrush Ai Tool logo

Semrush Ai Tool

Community
springvoiceswell

Semrush SEO AI-powered analysis tool MCP server & CLI for keyword research, domain analytics, backlink analysis

Publisherspringvoiceswell
Repositorysemrush-ai-tool
LanguageJavaScript
Forks
0
Stars
588
Available tools
0
Transport typestdio
Categories
LicenseMIT
Links
  • Connect tools to AI workflows

    Semrush Ai Tool exposes MCP capabilities that can be used by compatible AI clients and agents.

  • 0 available tools

    Browse the callable actions below, including names and descriptions when provided by the server.

  • Ready-to-copy setup

    Use the installation snippets to configure this server in your preferred MCP client.

  • Open source signals

    588 stars and 0 forks from the linked repository.

๐Ÿš€ 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 Node.js MCP Platform PRs Welcome

โšก 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:

Entry pointWho it's forWhat it does
๐Ÿค– MCP Server (semrush-ai-mcp)Marketers, SEOs, foundersGives Claude Desktop, Cursor & other AI clients 18 Semrush tools
โŒจ๏ธ CLI (semrush-ai)Developers, power users, AI coding agentsRun 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 โ€” 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:

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

ToolDescription
semrush_domain_overviewDomain overview across all databases โ€” traffic, keywords, Semrush rank
semrush_domain_rankOrganic & paid visibility in one regional database
semrush_domain_rank_historyMonthly historical rankings, keywords and traffic
semrush_domain_organic_keywordsKeywords the domain ranks for in Google's top 100
semrush_domain_paid_keywordsKeywords the domain bids on in Google Ads
semrush_domain_competitorsOrganic search competitors with competition level
semrush_domain_paid_competitorsPaid search (Google Ads) competitors

๐Ÿ” Keyword Research

ToolDescription
semrush_keyword_overviewVolume, CPC & competition across all databases
semrush_keyword_overview_single_dbDetailed metrics + trends in one database
semrush_related_keywordsRelated phrases & variations for content ideation
semrush_keyword_questionsQuestion keywords for FAQs & featured snippets
semrush_keyword_difficultyDifficulty index (0โ€“100), up to 100 keywords per call
semrush_keyword_serpDomains & URLs ranking organically for a keyword

๐Ÿ”— Backlink Analysis

ToolDescription
semrush_backlinks_overviewBacklinks, referring domains, IPs, follow/nofollow
semrush_backlinksIndividual backlinks with anchors & first/last seen
semrush_backlinks_refdomainsReferring domains sorted by authority

๐Ÿ“ˆ Traffic & ๐Ÿ’ณ Utility

ToolDescription
semrush_traffic_summaryVisits, uniques, bounce rate, duration (requires .Trends)
semrush_api_units_balanceRemaining 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

VariableDefaultDescription
SEMRUSH_API_KEY(required)Your Semrush API key
SEMRUSH_RATE_LIMIT_PER_SECOND10Max API requests per second
SEMRUSH_TIMEOUT_MS30000Per-request timeout

โž• 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

Installation

TypingMind
{
  "mcpServers": {
    "semrush-ai-tool": {
      "command": "npx",
      "args": [
        "-y",
        "github:springvoiceswell/semrush-ai-tool"
      ],
      "env": {
        "SEMRUSH_API_KEY": "<SEMRUSH_API_KEY>"
      }
    }
  }
}

Use Semrush Ai Tool MCP with multiple AI models

TypingMind connects MCP tools at the workspace level, so once Semrush Ai Tool is connected, you can use it with different AI models in TypingMind instead of setting it up separately for each model. This MCP runs locally through the TypingMind MCP connector on your device.

Setup guide to use the local connector

Use this when the MCP server needs access to local files, apps, or private resources on your computer.

1

Open the MCP settings

In TypingMind, go to Settings, Advanced Settings, then Model Context Protocol and choose Setup Connector.

  1. Open TypingMind in your browser.
  2. Click the Settings icon.
  3. Go to Advanced Settings.
  4. Open the Model Context Protocol section.
  5. Click Setup Connector and choose This Device.
TypingMind MCP connector setup screen with This Device selected
2

Run the connector command

Choose This Device, copy the command from TypingMind, and run it in Terminal. Keep the process running while you use MCP.

  1. Copy the setup command shown by TypingMind.
  2. Open Terminal on macOS or Windows Terminal on Windows.
  3. Paste and run the command.
  4. Approve the package install if Terminal asks you to proceed.
  5. Keep the Terminal window running while using MCP tools.
3

Add Semrush Ai Tool as a server

When the connector status is Ready, click Edit Servers and paste the MCP server configuration.

  1. Wait until the connector status shows Ready.
  2. Click Edit Servers.
  3. Paste the Semrush Ai Tool MCP server configuration.
  4. Save the server list.
  5. Refresh if you want to confirm the connector is still ready.
TypingMind MCP settings showing active server and Edit Servers button
{
  "mcpServers": {
    "semrush-ai-tool": {
      "command": "npx",
      "args": [
        "-y",
        "semrush-ai-tool"
      ]
    }
  }
}
4

Use it across models

Save the server list, open Plugins, enable the Semrush Ai Tool MCP tools, then select any supported AI model in TypingMind and use the tools in chat or assign them to an AI agent.

  1. Open the Plugins page in TypingMind.
  2. Enable the Semrush Ai Tool MCP tools.
  3. Start a chat and choose the AI model you want to use.
  4. Use the MCP tools in chat or assign them to an AI agent.
  5. Switch to another AI model whenever needed without reconnecting MCP.
TypingMind chat using enabled MCP tools with a selected AI model
Can you use Semrush Ai Tool to help me with this task?
Semrush Ai Tool
Sure. I read it.
Here is what I found using Semrush Ai Tool.

Frequently asked questions

What is the Semrush Ai Tool MCP server used for?

Semrush Ai Tool is an MCP server that lets compatible AI clients connect to external tools and context. In TypingMind, you can add this MCP server once and make its tools available in your AI workspace.

Can I use Semrush Ai Tool MCP with multiple AI models in TypingMind?

Yes. TypingMind connects MCP tools at the workspace level, so you can use Semrush Ai Tool with different AI models such as Claude, ChatGPT, Gemini, or other models you have configured in TypingMind without setting up the MCP server separately for each model.

Why use Semrush Ai Tool MCP with TypingMind?

TypingMind is one of the best frontends for LLM chat because it brings multiple AI models, prompts, plugins, AI agents, API keys, and MCP tools into one workspace. With Semrush Ai Tool connected, you can use its MCP tools across your preferred models while keeping your chat workflow organized in TypingMind.

How do I connect Semrush Ai Tool MCP to TypingMind?

Semrush Ai Tool runs through the TypingMind local MCP connector. This is best when the MCP server needs access to local files, desktop apps, command-line tools, or private resources on your computer.

What tools does Semrush Ai Tool MCP provide in TypingMind?

Semrush Ai Tool exposes MCP capabilities that can be enabled from the TypingMind Plugins page and used in chat or assigned to AI agents.

Do I need to share my API keys with TypingMind to use Semrush Ai Tool MCP?

No. TypingMind is local-first and lets you keep your model providers, API keys, prompts, and MCP configuration under your control. If Semrush Ai Tool requires authentication, add the required headers, OAuth settings, or local configuration for that MCP server when you create the connection.

Related MCP Servers

View all

Set up your own AI workspace now

Get notified about new features and future giveaways by subscribing to our newsletter ๐Ÿ‘‡