Semrush MCP Server

Semrush MCP

用于关键词研究、域名分析、反向链接、流量分析和竞争情报的 MCP 服务与 CLI。

由社区维护、可自托管的工具，通过两个入口提供 Semrush API 数据：用于 Claude Desktop 和 Cursor 等 AI 助手的 MCP 服务，以及可直接在终端中使用的 semrush CLI——非常适合开发者和 Claude Code 等可代为运行 shell 命令的 AI 编码 Agent。安装一次即可同时获得两者。

快速开始

npm install -g github:mrkooblu/semrush-mcp
export SEMRUSH_API_KEY=your_api_key_here

安装后，你可以使用两个命令：

• semrush — 用于终端和 Agent 的 CLI
• semrush-mcp — 通过 stdio 为 AI 客户端提供的 MCP 服务

CLI：

semrush domain semrush.com           # Domain overview
semrush kw "seo tools"               # Keyword overview
semrush backlinks semrush.com        # Backlink analysis

MCP 服务（添加到 AI 客户端配置中）：

{
  "mcpServers": {
    "semrush-mcp": {
      "command": "npx",
      "args": ["-y", "github:mrkooblu/semrush-mcp"],
      "env": {
        "SEMRUSH_API_KEY": "your-api-key"
      }
    }
  }
}

功能

• 域名分析 — 概览、排名追踪、排名历史、自然/付费关键词、竞争对手、广告历史、购物、独特页面
• URL 分析 — 每个 URL 的自然/付费关键词、排名、排名历史
• 子域名分析 — 每个子域名的排名、排名历史、自然关键词
• 子文件夹分析 — 每个子文件夹的自然/付费关键词、排名、排名历史、独特页面
• 关键词研究 — 概览、相关关键词、广泛匹配、问题、SERP 自然/付费结果、广告历史、难度
• 反向链接分析 — 反向链接、引用域名、概览、页面、锚文本、TLD 分布、类别
• 流量分析 — 摘要、来源、目标、地理位置、子域名、子文件夹、热门页面、排名、社交媒体（需要 .Trends）
• 受众情报 — 受众洞察、人口统计、购买转化、兴趣（需要 .Trends）
• Projects API — 列出、创建、更新、删除项目
• 站点审计 — 审计信息、快照、问题、页面、历史记录、启动爬取
• 关键词差距分析 — 并排比较两个域名的关键词概况（仅 CLI）
• API 单位余额 — 查看剩余 API 额度

所有功能均可通过 MCP 服务（77 个工具）和 CLI 使用。

安装

从 GitHub 全局安装

npm install -g github:mrkooblu/semrush-mcp

或克隆并在本地链接

git clone https://github.com/mrkooblu/semrush-mcp.git
cd semrush-mcp
npm install && npm run build && npm link

在环境变量或 .env 文件中设置 API 密钥：

export SEMRUSH_API_KEY=your_api_key_here

MCP 设置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "semrush-mcp": {
      "command": "npx",
      "args": ["-y", "github:mrkooblu/semrush-mcp"],
      "env": {
        "SEMRUSH_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

1. 前往 Settings > MCP Servers > Add Server
2. 配置：
   • 名称：Semrush MCP
   • 类型：command
   • 命令：node
   • 参数：/path/to/semrush-mcp/dist/index.js
   • 环境变量：SEMRUSH_API_KEY=your_api_key

其他 MCP 客户端

任何兼容 MCP 的客户端都可以使用 stdio 传输连接。将其指向 semrush-mcp 或 node dist/index.js，并设置 SEMRUSH_API_KEY 环境变量。

CLI 用法

semrush CLI 既适用于人工使用，也适用于 Claude Code 等可直接调用 shell 命令的 AI 编码 Agent。所有命令都支持 -d, --database <db>（国家/地区代码，默认值：us）、-l, --limit <n> 和 -f, --format <text|json>。

快速概览

自动识别关键词或域名：

semrush q "seo tools"              # Keyword overview
semrush q example.com              # Domain overview

域名分析

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

关键词研究

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

关键词难度

semrush kd "seo" "content marketing" "link building"

反向链接

semrush bl example.com                        # Backlink overview
semrush bl example.com --domains -l 20        # Referring domains

流量分析

需要 .Trends API 订阅。

semrush traffic example.com                   # Traffic summary
semrush traffic example.com --sources         # Traffic sources

关键词差距分析

semrush gaps mysite.com competitor.com -l 50

API 单位余额

semrush units

可用的 MCP 工具

域名分析（13 个工具）

工具	描述
semrush_domain_overview	域名概览 — 所有数据库中的流量、关键词和排名
semrush_domain_rank	域名在特定数据库中的排名
semrush_domain_rank_history	域名的历史排名数据
semrush_rank_difference	排名变化最大的域名
semrush_domain_organic_keywords	域名的自然搜索关键词
semrush_domain_paid_keywords	域名的付费搜索关键词
semrush_competitors	自然搜索竞争对手
semrush_paid_competitors	付费搜索竞争对手
semrush_domain_ads_history	域名的广告历史记录
semrush_domain_organic_unique	域名的独特自然搜索页面
semrush_domain_adwords_unique	域名的独特付费广告页面
semrush_domain_shopping	域名的购物广告/PLA 关键词
semrush_domain_shopping_unique	独特的购物广告页面

URL 分析（5 个工具）

工具	描述
semrush_url_organic	特定 URL 的自然搜索关键词
semrush_url_adwords	特定 URL 的付费搜索关键词
semrush_url_rank	特定 URL 的排名数据
semrush_url_rank_history	URL 的历史排名数据
semrush_url_ranks	URL 在所有数据库中的排名

子域名分析（4 个工具）

工具	描述
semrush_subdomain_rank	子域名的排名数据
semrush_subdomain_ranks	子域名在所有数据库中的排名
semrush_subdomain_rank_history	子域名的历史排名数据
semrush_subdomain_organic	子域名的自然搜索关键词

子目录分析（7 个工具）

工具	描述
semrush_subfolder_organic	子目录的自然搜索关键词
semrush_subfolder_adwords	子目录的付费搜索关键词
semrush_subfolder_rank	子目录的排名数据
semrush_subfolder_ranks	子目录在所有数据库中的排名
semrush_subfolder_rank_history	子目录的历史排名数据
semrush_subfolder_organic_unique	子目录中的独特自然搜索页面
semrush_subfolder_adwords_unique	子目录中的独特付费广告页面

反向链接（7 个工具）

工具	描述
semrush_backlinks	域名/URL 的反向链接
semrush_backlinks_domains	引荐域名
semrush_backlinks_overview	反向链接汇总统计
semrush_backlinks_pages	反向链接最多的页面
semrush_backlinks_anchors	锚文本分布
semrush_backlinks_tld	反向链接的顶级域名分布
semrush_backlinks_categories	反向链接的类别分布

关键词研究（10 个工具）

工具	描述
semrush_keyword_overview	所有数据库中的关键词概览
semrush_keyword_overview_single_db	特定数据库中的详细关键词数据
semrush_batch_keyword_overview	一次分析最多 100 个关键词
semrush_related_keywords	发现相关关键词
semrush_broad_match_keywords	广泛匹配/替代查询
semrush_phrase_questions	基于问题的关键词
semrush_keyword_organic_results	在自然搜索结果中排名的域名
semrush_keyword_paid_results	出现在付费搜索结果中的域名
semrush_keyword_ads_history	域名对某关键词出价的 12 个月历史记录
semrush_keyword_difficulty	排名进入前 10 的难度指数

流量与受众（17 个工具，需订阅 .Trends）

工具	描述
semrush_traffic_summary	域名流量摘要
semrush_traffic_sources	流量来源细分
semrush_traffic_destinations	访问后流量的去向
semrush_traffic_geo	流量的地域分布
semrush_traffic_subdomains	按子域名统计流量
semrush_traffic_subfolders	按子文件夹统计流量
semrush_traffic_top_pages	流量最高的页面
semrush_traffic_rank	随时间变化的流量排名
semrush_traffic_social_media	社交媒体流量细分
semrush_audience_insights	域名之间的受众重合情况
semrush_purchase_conversion	购买转化指标
semrush_household_distribution	家庭规模人口统计数据
semrush_income_distribution	收入人口统计数据
semrush_education_distribution	教育程度人口统计数据
semrush_occupation_distribution	职业人口统计数据
semrush_audience_interests	受众兴趣类别
semrush_traffic_accuracy	流量数据准确性估算

项目与站点审计（13 个工具）

工具	描述
semrush_list_projects	列出所有项目
semrush_get_project	获取项目详情
semrush_create_project	创建新项目
semrush_update_project	更新项目设置
semrush_delete_project	删除项目
semrush_site_audit_info	站点审计配置和状态
semrush_site_audit_snapshots	列出审计快照
semrush_site_audit_snapshot_detail	获取快照详情
semrush_site_audit_issues	审计问题元数据
semrush_site_audit_pages	列出已审计页面
semrush_site_audit_page_detail	页面级审计详情
semrush_site_audit_history	审计历史记录
semrush_site_audit_launch	启动新的审计爬取

实用工具（1 个工具）

工具	描述
semrush_api_units_balance	查看 API 单位余额

仅限 CLI 的命令

CLI 命令	描述
semrush gaps <d1> <d2>	分析两个域名之间的关键词差距

配置

需要在环境变量或 .env 文件中设置 SEMRUSH_API_KEY。

变量	默认值	描述
SEMRUSH_API_KEY	（必填）	你的 Semrush API 密钥
API_CACHE_TTL_SECONDS	300	API 响应的缓存 TTL
API_RATE_LIMIT_PER_SECOND	10	每秒最多 API 请求数
NODE_ENV	development	环境模式
LOG_LEVEL	info	日志级别

API 单位消耗

API 请求会消耗 Semrush 账户中的单位。不同报告的费用各不相同：

工具	每行消耗的 API 单位
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

随时使用 semrush units 或 semrush_api_units_balance MCP 工具查看余额。

开发

git clone https://github.com/mrkooblu/semrush-mcp.git
cd semrush-mcp
npm install
cp .env.example .env   # add your SEMRUSH_API_KEY

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 钩子

本项目使用 Husky 管理 Git 钩子：

• 提交前：lint-staged、ESLint、TypeScript 类型检查、单元测试、密钥检测
• 推送前：检查未提交的更改、完整构建、集成测试（需要 SEMRUSH_API_KEY）

为什么选择自行托管？

这款可自行托管的工具适合需要更多控制权的用户：

• 全面控制 API 调用和缓存 — 配置 TTL，检查原始响应
• 自定义速率限制 — 设置自己的每秒请求数限制
• 自行托管 / 隔离网络 — 完全在你的机器上运行，不依赖外部 MCP 端点
• 面向 Agent 的 CLI — AI 编码 Agent 可以直接调用 semrush，无需 MCP
• 开源 — 采用 MIT 许可证，可根据需求分叉并自定义

安全

• 切勿公开分享你的 Semrush API 密钥
• API 密钥可访问你的 API 单位余额
• 暴露凭据可能导致未经授权的 API 使用和意外费用

托管版替代方案

Semrush 还提供官方托管 MCP 连接器，地址为 https://mcp.semrush.com/v1/mcp——无需设置，使用你的 Semrush 账户进行身份验证。详情请参阅开始使用 MCP。

这是一个个人项目，并非 Semrush 官方产品。

许可证

MIT