npm package: @ilker10/semrush-mcp
Description: [![npm version](https://badge.fury.io/js/%40ilker10%2Fsemrush-mcp.svg)](https://badge.fury.io/js/%40ilker10%2Fsemrush-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](http
Author: ilker10
Latest version: 1.0.4

# 🚀 Semrush MCP Server

[![npm version](https://badge.fury.io/js/%40ilker10%2Fsemrush-mcp.svg)](https://badge.fury.io/js/%40ilker10%2Fsemrush-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

A comprehensive **Model Context Protocol (MCP) server** that provides seamless access to **Semrush SEO data** through AI assistants like Claude, n8n, and other MCP-compatible clients. Transform your SEO workflow with AI-powered keyword research, competitor analysis, and traffic insights.

## 📋 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Available Tools](#-available-tools)
- [n8n Integration](#-n8n-integration)
- [Configuration](#-configuration)
- [Usage Examples](#-usage-examples)
- [API Reference](#-api-reference)
- [Supported Databases](#-supported-databases)
- [Error Handling](#-error-handling)
- [Contributing](#-contributing)
- [License](#-license)

## ✨ Features

- **🔍 Comprehensive Keyword Analysis** - Search volume, difficulty, CPC, competition metrics
- **🏆 Domain Ranking Analysis** - Domain authority, organic traffic, keyword count metrics  
- **🎯 Competitor Discovery** - Identify organic competitors with relevance scoring
- **📊 Traffic Analytics** - Organic and paid keyword performance analysis
- **🔗 Related Keywords Discovery** - Semantic keyword expansion with multiple match types
- **🌍 Multi-language Support** - 142+ geographic databases including Turkish, German, French
- **⚡ Real-time Data** - Live Semrush API integration with up-to-date SEO metrics
- **🤖 AI-Ready** - Built for Claude Desktop, n8n, and other MCP-compatible platforms
- **🛡️ Error Resilient** - Comprehensive error handling and fallback mechanisms

## 📦 Installation

### NPX (Recommended)
```bash
# Run directly without installation
npx @ilker10/semrush-mcp
```

### Global Installation
```bash
# Install globally
npm install -g @ilker10/semrush-mcp

# Run the server
semrush-mcp
```

### Local Installation
```bash
# Install locally
npm install @ilker10/semrush-mcp

# Run from node_modules
npx @ilker10/semrush-mcp
```

## 🚀 Quick Start

### 1. Get Your Semrush API Key
1. Visit [Semrush API Documentation](https://www.semrush.com/api-documentation/)
2. Sign up for a Semrush Business plan with API access
3. Generate your API key from the subscription settings

### 2. Set Environment Variable
```bash
export SEMRUSH_API_KEY="your_api_key_here"
```

### 3. Run the Server
```bash
npx @ilker10/semrush-mcp
```

### 4. Connect to Your MCP Client
The server runs on stdio transport and can be connected to any MCP-compatible client.

## 🛠️ Available Tools

### 1. **Domain Overview** 
Get comprehensive domain analysis including domain ranking, organic keywords count, estimated traffic, and basic SEO metrics.

**Parameters:**
- `domain` (required): Target domain (e.g., "example.com")
- `database` (optional): Geographic database (default: "us")

**Returns:** Domain rank, organic keywords, traffic estimates, organic cost, AdWords data

### 2. **Keyword Analysis**
Comprehensive keyword research with difficulty, volume, and related keywords discovery.

**Parameters:**
- `keyword` (required): Target keyword to analyze
- `database` (optional): Geographic database (default: "us")
- `include_related` (optional): Include related keywords (default: false)
- `related_limit` (optional): Number of related keywords (default: 10, max: 50)

**Returns:** Search volume, CPC, competition, keyword difficulty, trends, optional related keywords

### 3. **Competitor Analysis**
Discover organic competitors and analyze competitive landscape with shared keyword analysis.

**Parameters:**
- `domain` (required): Target domain for competitor analysis
- `database` (optional): Geographic database (default: "us")
- `limit` (optional): Number of competitors to return (default: 20, max: 50)

**Returns:** Competitor domains, relevance scores, shared keywords, competitive insights

### 4. **Traffic Analytics**
Advanced traffic analysis including organic keywords performance and paid search insights.

**Parameters:**
- `domain` (required): Target domain
- `analysis_type` (optional): "organic_keywords", "paid_keywords", "top_keywords" (default: "organic_keywords")
- `database` (optional): Geographic database (default: "us")
- `limit` (optional): Number of results (default: 20, max: 100)

**Returns:** Keyword rankings, positions, traffic estimates, CPC data, competition metrics

### 5. **Related Keywords Discovery**
Advanced keyword expansion with semantic matching and filtering capabilities.

**Parameters:**
- `seed_keyword` (required): Primary keyword for expansion
- `match_type` (optional): "broad_match", "phrase_match", "exact_match", "questions", "related" (default: "broad_match")
- `database` (optional): Geographic database (default: "us")
- `volume_filter` (optional): Min/max search volume filtering
- `difficulty_filter` (optional): Min/max keyword difficulty filtering
- `limit` (optional): Number of results (default: 25, max: 100)

**Returns:** Related keywords, search volumes, competition data, intent information

## 🔧 n8n Integration

### Prerequisites
Ensure your n8n installation has the MCP Client Tool node available and the required environment variable is set:

```bash
# Required for n8n MCP Client Tool usage
export N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
```

### Setup in n8n

1. **Add MCP Client Tool Node**
   - Drag the "MCP Client Tool" node to your workflow
   - Configure the connection credentials

2. **Configure Connection**
   - **Command:** `npx`
   - **Arguments:** `-y @ilker10/semrush-mcp`
   - **Environments:** `SEMRUSH_API_KEY=your_api_key_here`

3. **Set Tool Parameters**
   Select your desired tool and configure parameters in JSON format:

   ```json
   {
     "keyword": "digital marketing",
     "database": "us",
     "include_related": true,
     "related_limit": 15
   }
   ```

### n8n Workflow Examples

#### Basic Keyword Research Workflow
```
Trigger → MCP Client Tool (keyword_analysis) → Process Results → Output
```

#### Competitor Analysis Workflow
```
Trigger → MCP Client Tool (domain_overview) → 
MCP Client Tool (competitor_analysis) → 
MCP Client Tool (traffic_analytics) →
AI Agent (competitive analysis) → 
Send Report
```

#### Content Planning Workflow
```
Manual Trigger → 
MCP Client Tool (related_keywords_discovery) → 
AI Agent (content ideas) → 
Notion/Airtable (save ideas)
```

### n8n Best Practices

- **Use AI Agents**: Combine MCP tools with AI Agent nodes for intelligent analysis
- **Error Handling**: Add error handling nodes for robust workflows
- **Data Processing**: Use Function nodes to process and format Semrush data
- **Automation**: Set up scheduled triggers for regular SEO monitoring
- **Integration**: Connect with other tools like Google Sheets, Slack, or email for reporting

## ⚙️ Configuration

### Environment Variables
```bash
# Required
SEMRUSH_API_KEY=your_semrush_api_key

# Optional (for debugging)
DEBUG=true
```

### MCP Client Configuration

#### Claude Desktop (claude_desktop_config.json)
```json
{
  "mcpServers": {
    "semrush": {
      "command": "npx",
      "args": ["-y", "@ilker10/semrush-mcp"],
      "env": {
        "SEMRUSH_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

#### VS Code MCP Configuration
```json
{
  "mcpServers": {
    "semrush": {
      "command": "npx",
      "args": ["-y", "@ilker10/semrush-mcp"],
      "env": {
        "SEMRUSH_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## 💡 Usage Examples

### Example 1: Basic Keyword Research
```json
{
  "tool": "keyword_analysis",
  "parameters": {
    "keyword": "best coffee makers",
    "database": "us",
    "include_related": true,
    "related_limit": 20
  }
}
```

### Example 2: Competitor Analysis
```json
{
  "tool": "competitor_analysis", 
  "parameters": {
    "domain": "competitor.com",
    "database": "us",
    "limit": 15
  }
}
```

### Example 3: Traffic Analytics - Paid Keywords
```json
{
  "tool": "traffic_analytics",
  "parameters": {
    "domain": "example.com",
    "analysis_type": "paid_keywords",
    "database": "us",
    "limit": 30
  }
}
```

### Example 4: Multi-language Research
```json
{
  "tool": "related_keywords_discovery",
  "parameters": {
    "seed_keyword": "kedi mamaları",
    "match_type": "broad_match",
    "database": "tr",
    "limit": 30
  }
}
```

### Example 5: Domain Overview Analysis
```json
{
  "tool": "domain_overview",
  "parameters": {
    "domain": "example.com",
    "database": "us"
  }
}
```
```json
{
  "tool": "related_keywords_discovery",
  "parameters": {
    "seed_keyword": "digital marketing",
    "match_type": "broad_match",
    "database": "us",
    "volume_filter": {
      "min_volume": 1000,
      "max_volume": 50000
    },
    "limit": 50
  }
}
```

## 📚 API Reference

### Response Format
All tools return data in a consistent format:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Tool results in CSV format with headers..."
    }
  ]
}
```

### Data Columns

#### Keyword Analysis
- **Ph**: Keyword phrase
- **Nq**: Search volume
- **Cp**: Cost per click (CPC)
- **Co**: Competition level (0-1)
- **Nr**: Number of results
- **Td**: Trend data
- **Kd**: Keyword difficulty (0-100)

#### Domain Analysis
- **Dn**: Domain name
- **Rk**: Domain rank
- **Or**: Organic keywords count
- **Ot**: Organic traffic estimate
- **Oc**: Organic traffic cost
- **Ad**: AdWords keywords count
- **At**: AdWords traffic estimate
- **Ac**: AdWords cost estimate

#### Competitor Analysis
- **Dn**: Competitor domain
- **Cr**: Competitor relevance score
- **Np**: Paid keywords overlap
- **Ad**: AdWords overlap
- **Td**: Total domains

#### Traffic Analytics
- **Ph**: Keyword/Page
- **Po**: Current position
- **Pp**: Previous position  
- **Pd**: Position difference
- **Tr**: Traffic estimate
- **Tc**: Traffic cost
- **Ur**: URL

## 🌍 Supported Databases

### Major Markets
- **us** - United States (English)
- **uk** - United Kingdom (English)
- **ca** - Canada (English)
- **au** - Australia (English)

### European Markets
- **de** - Germany (German)
- **fr** - France (French)
- **es** - Spain (Spanish)
- **it** - Italy (Italian)
- **nl** - Netherlands (Dutch)
- **tr** - Turkey (Turkish)

### Asian Markets
- **jp** - Japan (Japanese)
- **kr** - South Korea (Korean)
- **cn** - China (Chinese)
- **in** - India (English/Hindi)

### Latin American Markets
- **mx** - Mexico (Spanish)
- **br** - Brazil (Portuguese)
- **ar** - Argentina (Spanish)

*Total: 142+ geographic databases available*

## 🛡️ Error Handling

The server includes comprehensive error handling:

### Common Errors
- **ERROR 50 :: NOTHING FOUND**: No data available for the specified keyword/domain
- **Authentication Error**: Invalid or expired API key
- **Rate Limit**: API quota exceeded
- **Database Error**: Invalid geographic database specified

### Fallback Mechanisms
- Alternative API endpoints for failed requests
- Broader keyword matching when specific matches fail
- Helpful error messages with suggestions
- Graceful degradation for partial data

### Best Practices
- Use appropriate geographic databases for your target market
- Start with broader keywords before drilling down to specific terms
- Monitor API quota usage
- Implement retry logic in your applications

## 🔒 Security

- **API Key Protection**: Never commit API keys to version control
- **Environment Variables**: Use secure environment variable management
- **Access Control**: Limit API key permissions in Semrush dashboard
- **Network Security**: Use HTTPS for all API communications

## 📈 Performance

### Optimization Tips
- **Batch Requests**: Use related keyword discovery instead of multiple single requests
- **Appropriate Limits**: Set reasonable limits to avoid timeout issues
- **Caching**: Implement caching for frequently requested data
- **Geographic Targeting**: Use specific databases for better performance

### Rate Limits
- Semrush API has usage limits based on your subscription
- Monitor your API unit consumption
- Implement exponential backoff for failed requests

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. **Fork the Repository**
2. **Create a Feature Branch**: `git checkout -b feature/amazing-feature`
3. **Commit Changes**: `git commit -m 'Add amazing feature'`
4. **Push to Branch**: `git push origin feature/amazing-feature`
5. **Open Pull Request**

### Development Setup
```bash
# Clone the repository
git clone https://github.com/your-username/semrush-mcp.git

# Install dependencies
cd semrush-mcp
npm install

# Set up environment
cp .env.example .env
# Edit .env with your API key

# Run in development mode
npm run dev
```

### Testing
```bash
# Run tests
npm test

# Run with real API (requires valid key)
SEMRUSH_API_KEY=your_key npm run test:integration
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Semrush** for providing comprehensive SEO data through their API
- **Anthropic** for developing the Model Context Protocol standard
- **n8n Community** for automation platform integration
- **Open Source Community** for continuous improvements and feedback

## 📞 Support

### Documentation
- [Semrush API Documentation](https://developer.semrush.com/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [n8n MCP Integration Guide](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp/)

---

**Made with ❤️ for the SEO and AI automation community**

*Transform your SEO workflow with AI-powered insights!* 🚀