aayush1maggo/live-rank-tracker-mcp

Live SERP Rank Tracker MCP Server

A FastMCP 2.0 server for tracking live search engine rankings using the Serper.dev API. Track keyword rankings, monitor positions for specific domains, and get comprehensive search insights with location-based targeting.

Features

• Check Domain Rankings: Find the position of your domain for specific keywords
• Top Rankings: Get the top search results for any keyword
• Multi-Keyword Tracking: Track multiple keywords for a domain simultaneously
• Location-Based Search: Support for country and city-level targeting
• Search Insights: Get related searches, "People Also Ask", and knowledge graph data

Tools Available

1. check_ranking

Check the ranking position of a specific domain for a keyword.

Parameters:

• keyword (required): The search keyword
• domain (required): The domain to find (e.g., "apple.com")
• location (optional): City/region (e.g., "Melbourne, Victoria, Australia")
• country (optional): Country code (e.g., "au")

2. get_top_rankings

Get top ranking results for a keyword.

Parameters:

• keyword (required): The search keyword
• location (optional): City/region
• country (optional): Country code
• limit (optional): Number of results (default: 10, max: 100)

3. track_multiple_keywords

Track rankings for multiple keywords for a specific domain.

Parameters:

• keywords (required): List of keywords to track
• domain (required): The domain to track
• location (optional): City/region
• country (optional): Country code

4. get_search_insights

Get comprehensive search insights including related searches and people also ask.

Parameters:

• keyword (required): The search keyword
• location (optional): City/region
• country (optional): Country code

Setup

1. Install Dependencies

# Create virtual environment (if not already created)
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Unix/MacOS:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Configure API Key

1. Get your API key from Serper.dev
2. Copy .env.example to .env:

   cp .env.example .env
   

3. Edit .env and add your API key:

   SERPER_API_KEY=your_actual_api_key_here
   

3. Test the API Connection (Optional)

Before running the full server, you can test the Serper API connection:

python test_server.py

This will verify your API key works and show sample results.

4. Run the Server

# Make sure your virtual environment is activated
python server.py

Or use FastMCP's development mode:

fastmcp dev server.py

5. Configure with Claude Desktop (Optional)

To use this server with Claude Desktop, add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "live-rank-tracker": {
      "command": "python",
      "args": ["C:\\Users\\hp\\code\\mcp\\live-rank-tracker\\server.py"],
      "env": {
        "SERPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace the path and API key with your actual values.

Usage Examples

Example 1: Check Domain Ranking

check_ranking(
    keyword="apple inc",
    domain="apple.com",
    location="Melbourne, Victoria, Australia",
    country="au"
)

Example 2: Get Top 10 Rankings

get_top_rankings(
    keyword="python programming",
    location="New York, NY, USA",
    country="us",
    limit=10
)

Example 3: Track Multiple Keywords

track_multiple_keywords(
    keywords=["apple inc", "apple stock", "apple news"],
    domain="apple.com",
    location="San Francisco, CA, USA",
    country="us"
)

Example 4: Get Search Insights

get_search_insights(
    keyword="machine learning",
    location="London, England, UK",
    country="uk"
)

Country Codes

Common country codes for the country parameter:

• us - United States
• uk - United Kingdom
• au - Australia
• ca - Canada
• de - Germany
• fr - France
• jp - Japan
• in - India

Location Format

Locations should be formatted as: "City, State/Province, Country"

Examples:

• "New York, NY, USA"
• "London, England, UK"
• "Melbourne, Victoria, Australia"
• "Toronto, Ontario, Canada"

Response Format

All tools return JSON responses with relevant ranking data:

{
  "keyword": "apple inc",
  "domain": "apple.com",
  "position": 1,
  "url": "https://www.apple.com",
  "title": "Apple",
  "snippet": "Discover the innovative world of Apple...",
  "location": "Melbourne, Victoria, Australia",
  "country": "au",
  "found": true
}

Error Handling

The server includes comprehensive error handling:

• API key validation
• Request timeout handling (30 seconds)
• Detailed error messages in JSON format

Notes

• The Serper API has rate limits based on your subscription plan
• Results are fetched in real-time from Google
• Position counting starts at 1 (first organic result)
• The server searches through organic results only (excludes ads)

License

MIT