fetchserp-mcp-server/README.md

A Model Context Protocol (MCP) server that provides access to FetchSERP API for SEO analysis, SERP data, web scraping, and keyword research. Supports both stdio and HTTP transport modes.

# FetchSERP MCP Server

A Model Context Protocol (MCP) server that exposes the FetchSERP API for SEO, SERP analysis, web scraping, and keyword research.

## Features

This MCP server provides access to all FetchSERP API endpoints:

### SEO & Analysis
- **Domain Analysis**: Get backlinks, domain info (DNS, WHOIS, SSL, tech stack)
- **Keyword Research**: Search volume, suggestions, long-tail keyword generation
- **SEO Analysis**: Comprehensive webpage SEO analysis
- **AI Analysis**: AI-powered webpage analysis with custom prompts
- **Moz Integration**: Domain authority and Moz metrics

### SERP & Search
- **Search Results**: Get SERP results from Google, Bing, Yahoo, DuckDuckGo
- **AI Overview**: Google's AI overview with JavaScript rendering
- **Enhanced Results**: SERP with HTML or text content
- **Ranking Check**: Domain ranking for specific keywords
- **Indexation Check**: Verify if pages are indexed

### Web Scraping
- **Basic Scraping**: Scrape webpages without JavaScript
- **JS Scraping**: Execute custom JavaScript on pages
- **Proxy Scraping**: Scrape with country-specific proxies
- **Domain Scraping**: Scrape multiple pages from a domain

### User Management
- **Account Info**: Check API credits and user information

## Installation

**No installation required!** This MCP server runs directly from GitHub using npx.

**Get your FetchSERP API token**: Sign up at [https://www.fetchserp.com](https://www.fetchserp.com) to get your API token. New users get 250 free credits to get started!

## Usage

### Transport Modes

This MCP server supports two transport modes:

**npx mode (Option 1)**:
- ✅ Zero installation required
- ✅ Always gets latest version from GitHub
- ✅ Perfect for individual users
- ✅ Runs locally with Claude Desktop

**HTTP mode (Option 2)**:
- ✅ Remote deployment capability
- ✅ Multiple clients can connect
- ✅ Better for enterprise/team environments
- ✅ Centralized server management
- ✅ Single API key authentication (FetchSERP token)
- ✅ Scalable architecture

### Configuration

**Option 1: Using npx (Local/Remote GitHub)**
Add this server to your MCP client configuration. For example, in Claude Desktop using github registry :

```json
{
  "mcpServers": {
    "fetchserp": {
      "command": "npx",
      "args": [
        "github:fetchSERP/fetchserp-mcp-server-node"
      ],
      "env": {
        "FETCHSERP_API_TOKEN": "your_fetchserp_api_token_here"
      }
    }
  }
}
```

or using npm registry

```json
{
  "mcpServers": {
    "fetchserp": {
      "command": "npx",
      "args": ["fetchserp-mcp-server"],
      "env": {
        "FETCHSERP_API_TOKEN": "your_fetchserp_api_token_here"
      }
    }
  }
}
```

**Option 2: Claude API with MCP Server**
For programmatic usage with Claude's API and your deployed MCP server:

```javascript
const claudeRequest = {
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [
    {
      role: "user", 
      content: question
    }
  ],
  // MCP Server Configuration
  mcp_servers: [
    {
      type: "url",
      url: "https://mcp.fetchserp.com/sse",
      name: "fetchserp",
      authorization_token: FETCHSERP_API_TOKEN,
      tool_configuration: {
        enabled: true
      }
    }
  ]
};

const response = await httpRequest('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': CLAUDE_API_KEY,
    'anthropic-version': '2023-06-01',
    'anthropic-beta': 'mcp-client-2025-04-04',
    'content-type': 'application/json'
  }
}, JSON.stringify(claudeRequest));
```

**Option 3: OpenAI API with MCP Server**
For programmatic usage with OpenAI's API and your deployed MCP server:

```javascript
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const res = await openai.responses.create({
  model: "gpt-4.1",
  tools: [
    {
      type: "mcp",
      server_label: "fetchserp",
      server_url: "https://mcp.fetchserp.com/sse",
      headers: {
        Authorization: `Bearer ${FETCHSERP_API_TOKEN}`
      }
    }
  ],
  input: question
});

console.log(res.choices[0].message);
```

**Option 4: Docker**
Use the pre-built Docker image from GitHub Container Registry for containerized deployment:

```json
{
  "mcpServers": {
    "fetchserp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FETCHSERP_API_TOKEN",
        "ghcr.io/fetchserp/fetchserp-mcp-server-node:latest"
      ],
      "env": {
        "FETCHSERP_API_TOKEN": "your_fetchserp_api_token_here"
      }
    }
  }
}
```

**Docker Features:**
- ✅ Containerized deployment
- ✅ Cross-platform compatibility (ARM64 & AMD64)
- ✅ Isolated environment
- ✅ Easy scaling and deployment
- ✅ Automated builds from GitHub

**Manual Docker Usage:**
```bash
# Pull the latest image
docker pull ghcr.io/fetchserp/fetchserp-mcp-server-node:latest

# Run with environment variable
docker run -i --rm \
  -e FETCHSERP_API_TOKEN="your_token_here" \
  ghcr.io/fetchserp/fetchserp-mcp-server-node:latest

# Or run in HTTP mode on port 8000
docker run -p 8000:8000 \
  -e FETCHSERP_API_TOKEN="your_token_here" \
  -e MCP_HTTP_MODE=true \
  ghcr.io/fetchserp/fetchserp-mcp-server-node:latest
```

## Available Tools

### Domain & SEO Analysis

#### `get_backlinks`
Get backlinks for a domain
- **domain** (required): Target domain
- **search_engine**: google, bing, yahoo, duckduckgo (default: google)
- **country**: Country code (default: us)
- **pages_number**: Pages to search 1-30 (default: 15)

#### `get_domain_info`
Get comprehensive domain information
- **domain** (required): Target domain

#### `get_domain_emails`
Extract emails from a domain
- **domain** (required): Target domain
- **search_engine**: Search engine (default: google)
- **country**: Country code (default: us)
- **pages_number**: Pages to search 1-30 (default: 1)

#### `get_playwright_mcp`
Use GPT-4.1 to remote control a browser via a Playwright MCP server
- **prompt** (required): The prompt to use for remote control of the browser

*This endpoint uses GPT-4.1 to remote control a browser via a Playwright MCP server.*

#### `get_webpage_seo_analysis`
Comprehensive SEO analysis of a webpage
- **url** (required): URL to analyze

#### `get_webpage_ai_analysis`
AI-powered webpage analysis
- **url** (required): URL to analyze
- **prompt** (required): Analysis prompt

#### `generate_wordpress_content`
Generate WordPress content using AI with customizable prompts and models
- **user_prompt** (required): The user prompt
- **system_prompt** (required): The system prompt  
- **ai_model**: The AI model (default: gpt-4.1-nano)

*Generates SEO-optimized WordPress content including title and content (800-1500 words) with keyword targeting in the first 100 words.*

#### `generate_social_content`
Generate social media content using AI with customizable prompts and models
- **user_prompt** (required): The user prompt
- **system_prompt** (required): The system prompt
- **ai_model**: The AI model (default: gpt-4.1-nano)

*Generates engaging social media content optimized for various platforms and audiences.*

#### `get_moz_analysis`
Get Moz domain authority and metrics
- **domain** (required): Target domain

### Keyword Research

#### `get_keywords_search_volume`
Get search volume for keywords
- **keywords** (required): Array of keywords
- **country**: Country code

#### `get_keywords_suggestions`
Get keyword suggestions
- **url**: URL to analyze (optional if keywords provided)
- **keywords**: Array of seed keywords (optional if url provided)
- **country**: Country code

#### `get_long_tail_keywords`
Generate long-tail keywords
- **keyword** (required): Seed keyword
- **search_intent**: informational, commercial, transactional, navigational (default: informational)
- **count**: Number to generate 1-500 (default: 10)

### SERP & Search

#### `get_serp_results`
Get search engine results
- **query** (required): Search query
- **search_engine**: google, bing, yahoo, duckduckgo (default: google)
- **country**: Country code (default: us)
- **pages_number**: Pages to search 1-30 (default: 1)

#### `get_serp_html`
Get SERP results with HTML content
- Same parameters as `get_serp_results`

#### `get_serp_text`
Get SERP results with text content
- Same parameters as `get_serp_results`

#### `get_serp_ai_mode`
Get SERP with AI Overview and AI Mode response
- **query** (required): Search query
- **country**: Country code (default: us)

*Returns AI overview and AI mode response for the query. Less reliable than the 2-step process but returns results in under 30 seconds.*

#### `check_page_indexation`
Check if domain is indexed for keyword
- **domain** (required): Target domain
- **keyword** (required): Search keyword

#### `get_domain_ranking`
Get domain ranking for keyword
- **keyword** (required): Search keyword
- **domain** (required): Target domain
- **search_engine**: Search engine (default: google)
- **country**: Country code (default: us)
- **pages_number**: Pages to search 1-30 (default: 10)

### Web Scraping

#### `scrape_webpage`
Scrape webpage without JavaScript
- **url** (required): URL to scrape

#### `scrape_domain`
Scrape multiple pages from domain
- **domain** (required): Target domain
- **max_pages**: Maximum pages to scrape, up to 200 (default: 10)

#### `scrape_webpage_js`
Scrape webpage with custom JavaScript
- **url** (required): URL to scrape
- **js_script** (required): JavaScript code to execute

#### `scrape_webpage_js_proxy`
Scrape webpage with JavaScript and proxy
- **url** (required): URL to scrape
- **country** (required): Proxy country
- **js_script** (required): JavaScript code to execute

### User Management

#### `get_user_info`
Get user information and API credits
- No parameters required

## API Token

You need a FetchSERP API token to use this server. 

**Getting your API token:**
1. Sign up at [https://www.fetchserp.com](https://www.fetchserp.com)
2. New users automatically receive **250 free credits** to get started
3. Your API token will be available in your dashboard

Set the token as an environment variable:
```bash
export FETCHSERP_API_TOKEN="your_token_here"
```

## Error Handling

The server includes comprehensive error handling:
- Missing API token validation
- API response error handling
- Input validation
- Proper MCP error responses


## Docker deploy

```
docker build --platform=linux/amd64 -t olivier86/fetchserp-mcp-server-node:latest --push .
docker build --platform=linux/amd64 -t ghcr.io/fetchserp/mcp-server-node:latest --push .

docker run -p 8000:8000 olivier86/fetchserp-mcp-server-node:latest
```

## To start tunneling
```
nohup ngrok http 8000 --domain guinea-dominant-jolly.ngrok-free.app > /var/log/ngrok.log 2>&1 &
```

npm login
npm publish --access public