SEO Research MCP
Free SEO research tools for AI-powered IDEs
Features • Installation • IDE Setup • API Reference • Contributing • Credits
[!CAUTION]
⚠️ Educational Use Only
This project is for educational and research purposes only.
- This tool interfaces with third-party services (Ahrefs, CapSolver)
- Users must comply with all applicable terms of service
- The authors do not endorse any use that violates third-party ToS
- Use responsibly and at your own risk
By using this software, you acknowledge that you understand and accept these terms.
🎯 What is this?
SEO Research MCP brings powerful SEO research capabilities directly into your AI coding assistant. Using the Model Context Protocol (MCP), it connects your IDE to Ahrefs' SEO data, allowing you to:
- Research competitor backlinks while coding
- Generate keyword ideas without leaving your editor
- Analyze traffic patterns for any website
- Check keyword difficulty before creating content
✨ Features
| Feature | Description | Example Use |
|---|---|---|
| 🔗 Backlink Analysis | Domain rating, anchor text, edu/gov links | "Show me backlinks for competitor.com" |
| 🔑 Keyword Research | Generate ideas from seed keywords | "Find keywords related to 'python tutorial'" |
| 📊 Traffic Analysis | Monthly traffic, top pages, countries | "What's the traffic for example.com?" |
| 📈 Keyword Difficulty | KD score with full SERP breakdown | "How hard is 'best laptop 2025' to rank for?" |
📋 Prerequisites
Before you start, you'll need:
-
Python 3.10 or higher
python --version # Should be 3.10+ -
CapSolver API Key (for CAPTCHA solving)
📦 Installation
Option 1: From PyPI (Recommended)
pip install seo-mcp
Or using uv:
uv pip install seo-mcp
Option 2: From Source
git clone https://github.com/egebese/seo-research-mcp.git
cd seo-research-mcp
pip install -e .
🛠️ IDE Setup Guides
Choose your IDE and follow the setup instructions:
🟣 Claude Desktop
Step 1: Open Config File
- Open Claude Desktop
- Go to Settings → Developer → Edit Config
Step 2: Add Configuration
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"seo-research": {
"command": "uvx",
"args": ["--python", "3.10", "seo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Step 3: Restart & Verify
- Restart Claude Desktop
- Look for the hammer/tools icon in the bottom-right corner
📁 Config file locations:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
🔵 Claude Code (CLI)
Option A: Quick Setup (CLI)
# Add the MCP server
claude mcp add seo-research --scope user -- uvx --python 3.10 seo-mcp
# Set your API key
export CAPSOLVER_API_KEY="YOUR_API_KEY_HERE"
Option B: Config File
Add to ~/.claude.json:
{
"mcpServers": {
"seo-research": {
"command": "uvx",
"args": ["--python", "3.10", "seo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Verify Installation
claude mcp list
🟢 Cursor
Global Setup (All Projects)
Create ~/.cursor/mcp.json:
{
"mcpServers": {
"seo-research": {
"command": "uvx",
"args": ["--python", "3.10", "seo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Project Setup (Single Project)
Create .cursor/mcp.json in your project root with the same content.
Verify Installation
- Go to File → Preferences → Cursor Settings
- Select MCP in the sidebar
- Check that
seo-researchappears under Available Tools
🌊 Windsurf
Step 1: Open Settings
- Mac:
Cmd + Shift + P→ "Open Windsurf Settings" - Windows/Linux:
Ctrl + Shift + P→ "Open Windsurf Settings"
Step 2: Add Configuration
Navigate to Cascade → MCP Servers → Edit raw mcp_config.json:
{
"mcpServers": {
"seo-research": {
"command": "uvx",
"args": ["--python", "3.10", "seo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
📁 Config location: ~/.codeium/windsurf/mcp_config.json
💜 VS Code (GitHub Copilot)
⚠️ Requires VS Code 1.102+ with GitHub Copilot
Setup
Create .vscode/mcp.json in your workspace:
{
"servers": {
"seo-research": {
"command": "uvx",
"args": ["--python", "3.10", "seo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Activate
- Open the
.vscode/mcp.jsonfile - Click the Start button that appears
- In Chat view, click Tools to toggle MCP tools
- Use
#tool_namein prompts to invoke tools
⚡ Zed
Setup
Add to your Zed settings.json:
{
"context_servers": {
"seo-research": {
"command": {
"path": "uvx",
"args": ["--python", "3.10", "seo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
}
Verify
- Open Agent Panel settings
- Check the indicator dot next to
seo-research - Green dot = Server is active
📖 API Reference
get_backlinks_list(domain)
Get backlink data for any domain.
# Input
domain: str # e.g., "example.com"
# Output
{
"overview": {
"domainRating": 76,
"backlinks": 1500,
"refDomains": 300
},
"backlinks": [
{
"anchor": "Example link",
"domainRating": 76,
"title": "Page title",
"urlFrom": "https://source.com/page",
"urlTo": "https://example.com/page",
"edu": false,
"gov": false
}
]
}
keyword_generator(keyword, country?, search_engine?)
Generate keyword ideas from a seed keyword.
# Input
keyword: str # Seed keyword
country: str # Default: "us"
search_engine: str # Default: "Google"
# Output
[
{
"keyword": "example keyword",
"volume": 1000,
"difficulty": 45
}
]
get_traffic(domain_or_url, country?, mode?)
Estimate search traffic for a website.
# Input
domain_or_url: str # Domain or full URL
country: str # Default: "None" (all countries)
mode: str # "subdomains" | "exact"
# Output
{
"traffic": {
"trafficMonthlyAvg": 50000,
"costMontlyAvg": 25000
},
"top_pages": [...],
"top_countries": [...],
"top_keywords": [...]
}
keyword_difficulty(keyword, country?)
Get keyword difficulty score with SERP analysis.
# Input
keyword: str # Keyword to analyze
country: str # Default: "us"
# Output
{
"difficulty": 45,
"serp": [...]
}
⚙️ How It Works
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Your │ │ CapSolver │ │ Ahrefs │ │ Formatted │
│ AI IDE │────▶│ (CAPTCHA) │────▶│ API │────▶│ Results │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
- Request → Your AI assistant calls an MCP tool
- CAPTCHA → CapSolver handles Cloudflare verification
- Data → Ahrefs API returns SEO data
- Response → Formatted results appear in your IDE
🐛 Troubleshooting
| Problem | Solution |
|---|---|
| "CapSolver API key error" | Check CAPSOLVER_API_KEY is set correctly |
| Rate limiting | Wait a few minutes, reduce request frequency |
| No results | Domain may not be indexed by Ahrefs |
| Server not appearing | Restart your IDE after config changes |
| Connection timeout | Check your internet connection |
🤝 Contributing
Contributions are welcome! Here's how you can help:
Ways to Contribute
- 🐛 Report Bugs - Found an issue? Open a bug report
- 💡 Suggest Features - Have an idea? Request a feature
- 📝 Improve Docs - Fix typos, clarify instructions, add examples
- 🔧 Submit Code - Bug fixes, new features, optimizations
Development Setup
# Clone the repo
git clone https://github.com/egebese/seo-research-mcp.git
cd seo-research-mcp
# Install dependencies
uv sync
# Run locally
python main.py
Pull Request Process
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
Code Guidelines
- Keep code simple and readable
- Add comments for complex logic
- Test your changes before submitting
- Follow existing code style
📊 Star History
📄 License
This project is licensed under the MIT License with an educational use notice.
See LICENSE for full details.
🙏 Credits
This project is a fork of seo-mcp by @cnych.
Special thanks to the original author for creating this tool.
⭐ If this helps your SEO research, consider giving it a star! ⭐