Keyword Research Tool MCP Server

# Keyword Research Tool MCP Server An MCP (Model Context Protocol) server that provides comprehensive SEO keyword research and analysis capabilities. This server adapts the functionality from the original [boringmarketer/keyword-research-tool](https://github.com/boringmarketer/keyword-research-tool) into a single, powerful MCP tool. ## Features 🔍 **Comprehensive Analysis** - Website content crawling and analysis using Firecrawl - AI-powered seed keyword generation with Perplexity - Search volume and competition data via DataForSEO - Smart keyword clustering and competitor analysis - Timestamped report generation 📊 **Detailed Reports** - Keyword clusters with commercial intent scoring - Quick wins (low competition opportunities) - High-value targets (commercial keywords) - Competitor domain analysis with AI research - Actionable SEO strategy recommendations - Dual format: JSON (technical) + Text (human-readable) - Professional text reports matching original HTML tool format 🎯 **Business-Focused** - Auto-detects and optimizes for business type - Commercial intent scoring for ROI focus - Industry-specific keyword suggestions - Professional report format ## Prerequisites You'll need API keys from these services: ### Required APIs 1. **Firecrawl** (Website Scraping) - Sign up at: https://firecrawl.dev/ - Format: `fc-xxxxxxxxxx` - Cost: ~$0.01 per website scrape 2. **Perplexity** (AI Keyword Generation) - Sign up at: https://www.perplexity.ai/ - Format: `pplx-xxxxxxxxxx` - Cost: ~$0.02 per keyword generation 3. **DataForSEO** (Keyword & SERP Data) - Sign up at: https://dataforseo.com/ - Uses your login credentials (username/password) - Cost: ~$0.50-1.00 per analysis **Total estimated cost per analysis: ~$0.53-1.03** ## Installation 1. **Clone and install dependencies:** ```bash git clone <this-repo> cd keyword-research-tool-mcp npm install npm run build ``` 2. **Add to your MCP client configuration** (e.g., in Claude Desktop's config): ```json { "mcpServers": { "seo-keyword-research": { "command": "node", "args": ["path/to/keyword-research-tool-mcp/dist/index.js"], "env": { "FIRECRAWL_API_KEY": "fc-xxxxxxxxxxxxxxxxxxxxxxxxxx", "PERPLEXITY_API_KEY": "pplx-xxxxxxxxxxxxxxxxxxxxxxxxxx", "DATAFORSEO_USERNAME": "your-username", "DATAFORSEO_PASSWORD": "your-password" } } } } ``` If you are running a tool like Cursor or Windsurf, you may need to remind it to search for API keys in the above JSON file. ### 3. Build the Server ```bash npm run build ``` ## Usage The server provides one comprehensive tool: ### `analyze_website` Performs complete SEO keyword research and analysis for any website. **Parameters:** - `website_url` (string): Website URL to analyze (e.g., "https://example.com") - `business_type` (enum): Business type for targeted analysis - Options: "E-commerce", "SaaS", "Service Business", "Blog/Content", "Education", "Other" - `firecrawl_api_key` (string): Firecrawl API key (format: fc-xxxxxxxxxx) - `perplexity_api_key` (string): Perplexity API key (format: pplx-xxxxxxxxxx) - `dataforseo_username` (string): DataForSEO username (your email) - `dataforseo_password` (string): DataForSEO password **Example Usage:** ``` analyze_website({ "website_url": "https://example.com", "business_type": "SaaS", "firecrawl_api_key": "fc-your-key-here", "perplexity_api_key": "pplx-your-key-here", "dataforseo_username": "your@email.com", "dataforseo_password": "your_password" }) ``` ## Output The analysis generates: ### Console Output - **Analysis Summary**: Total keywords, search volume, traffic potential - **Quick Wins**: Low competition opportunities for immediate targeting - **High-Value Targets**: Keywords with highest commercial potential - **Top Keyword Clusters**: Organized keyword groups with metrics - **Main Competitors**: Competing domains identified - **Report Location**: Path to detailed JSON report ### Saved Reports Timestamped reports are automatically saved to `reports/` directory in two formats: **JSON Report** (`<company domain>_YYYY-MM-DD_HH-MM-SS.json`): - Complete analysis data for technical use - All keyword metrics and search volumes - Competitor domains and SERP analysis - Commercial intent scores - Clustering analysis - Raw API response data **Text Report** (`<company domain>_YYYY-MM-DD_HH-MM-SS_formatted.txt`): - Comprehensive formatted report matching the original HTML tool - Executive summary with key metrics - Quick wins section (low competition opportunities) - High-value targets (commercial keywords) - Detailed keyword clusters with complete breakdowns - Competitor analysis with AI and SERP sources - Strategic action plan (immediate, medium-term, long-term) - Raw analysis data section - Professional formatting with ASCII art borders ## Analysis Process The tool follows the same comprehensive process as the original app.js: 1. **Website Scraping**: Extract content using Firecrawl API 2. **Content Cleaning**: Filter technical terms, focus on business-relevant content 3. **Keyword Generation**: AI-powered seed keyword creation with Perplexity 4. **Keyword Enhancement**: Get search volumes, competition data via DataForSEO 5. **SERP Analysis**: Analyze top-ranking pages and competitor domains 6. **Clustering**: Group related keywords into themed clusters 7. **Scoring**: Calculate commercial intent and difficulty scores 8. **Report Generation**: Create comprehensive analysis report ## Code Structure The MCP server is built by adapting the original `app.js` functions: ``` src/index.ts ├── KeywordResearchTool class │ ├── scrapeWebsite() # Website content extraction │ ├── cleanWebsiteContent() # Content filtering and cleaning │ ├── generateKeywords() # AI keyword generation │ ├── filterTechnicalKeywords() # Remove irrelevant terms │ └── performAnalysis() # Main orchestration function ├── MCP Server setup │ ├── Tool definition (analyze_website) │ ├── Request handlers │ └── Response formatting └── Report generation and file saving ``` ## Key Adaptations from Original - **Single Tool**: Condensed the multi-step web UI into one comprehensive MCP tool - **Simplified Flow**: Removed UI progress indicators, kept core analysis logic - **Enhanced Output**: Structured markdown output plus detailed JSON reports - **Type Safety**: Full TypeScript implementation with proper interfaces - **Error Handling**: Comprehensive error messages and validation - **Report Persistence**: Automatic timestamped report saving ## Development **Build the project:** ```bash npm run build ``` **Run in development mode:** ```bash npm run dev ``` **Start the server:** ```bash npm start ``` ## Troubleshooting ### Common Issues **"Analysis failed" errors:** - Verify all API keys are correct and active - Check API credit balances - Ensure website URL is accessible - Test individual API endpoints **"Failed to scrape website":** - Check if website blocks crawlers/bots - Try with different website URL - Verify Firecrawl API key format and permissions **DataForSEO errors:** - Confirm username/password are correct - Check account has sufficient credits - Some keywords may have limited data available ### API Documentation - **Firecrawl**: https://docs.firecrawl.dev/ - **Perplexity**: https://docs.perplexity.ai/ - **DataForSEO**: https://docs.dataforseo.com/ ## License MIT License - Feel free to use and modify for your SEO research needs. --- **Built for marketers and SEO professionals who want comprehensive keyword research integrated into their AI workflows.**