Haloscan-mcp-server by occirank - MCP Server

Haloscan MCP Server

A Model Context Protocol (MCP) server for interacting with the Haloscan SEO API. This server allows easy integration with Claude for Desktop, N8N, and other MCP-compatible clients.

Features

Exposes Haloscan SEO API functionality through MCP tools
Provides prompts for common SEO tasks
Easy integration with workflow automation tools like N8N

Tools

1. User Tools

get_user_credit
- Retrieves the remaining credit for the user identified by the provided API key.

2. Keyword Explorer Tools

get_keywords_overview
- Retrieves an overview of a specific keyword, providing key performance indicators such as search volume, competition level, and trends over time.
- Inputs:
  - keyword (string): Requested keyword.
  - requested_data (string[]): Any combination of [keyword_match, related_search, related_question, similar_category, similar_serp, top_sites, similar_highlight, categories, metrics, volume_history, serp ].
    It is mandatory to specify at least one of the requested data. Here is what they mean:
    - keyword_match: Top 10 (wrt search volume) keywords that include the provided keyword in their search query (exact match).
    - related_search: Top 10 (wrt search volume) keywords that appear in SERP's "Related Searches" section for the provided keyword.
    - related_question: Top 10 (wrt search volume) keywords that appear in SERP's "People Also Ask" (or in "Related Searches if the keyword is obviously a question) section for the provided keyword.
    - similar_category: Top 10 (wrt search volume) keywords that have the same "Products & Services" category tree as the provided keyword. Careful, fetching this data significantly increases response time.
    - similar_serp: Top 10 (wrt SERP similarity) keywords that have a similar organic SERP as the provided keyword.
    - top_sites: Top 10 (wrt visibility) websites that rank for the provided keyword and similar ones.
    - similar_highlight: Top 10 (wrt search volume) keywords for which similar terms are highlighted in SERP result pages.
    - categories: List of Products & Services categories the provided keyword belongs to.
    - metrics: List of metrics for the provided keyword. Those metrics include:
      - Ads metrics: volume, competition, CPC. Your usual ads data.
      - SEO metrics: corrected search volume, keyword match count, allintitle, KGR, KVI (Keyword Visibility Index).
    - volume_history: Up to 2 years of search volume history for the provided keyword.
    - serp: Last organic SERP for the provided keyword.
get_keywords_match
- Retrieves keywords/expressions including the provided keyword as a substring.
- Input:
  - keyword (string): Requested keyword.
get_keywords_highlights
- Retrieves keywords/expressions for which similar terms are highlighted in SERP result pages.
- Input:
  - keyword (string): Requested keyword.
get_keywords_related
- Retrieves keywords/expressions that appear in SERP's "Related Searches" section for the provided keyword.
- Input:
  - keyword (string): Requested keyword.
get_keywords_questions
- Retrieves keywords/expressions that appear in SERP's "People Also Ask" (or in "Related Searches if the keyword is obviously a question) section for the provided keyword.
- Input:
  - keyword (string): Requested keyword.
get_keywords_find
- Retrieves comprehensive data for a given keyword OR list of keywords, including SEO metrics & ads metrics. This endpoint is a wrapper to call get_keywords_match, get_keywords_related, get_keywords_questions, get_keywords_highlights together.
- Inputs:
  - keyword (string): Requested keyword.
  - keywords (string[]): Requested keywords. Ignored if keyword is provided.
  - keywords_sources (string[]): Which strategies to use to find keywords from input (Any combination of [match, serp, related, highlights, questions]).
    At least one is required. Here is what they mean:
    - match: Keywords/expressions that include the provided keyword in their search query (exact match).
    - serp: Keywords/expressions that have a similar organic SERP as the provided keyword.
    - related: Keywords/expressions that appear in SERP's "Related Searches" section for the provided keyword.
    - highlights: Keywords/expressions for which similar terms are highlighted in SERP result pages.
    - questions: Keywords/expressions that appear in SERP's "People Also Ask" (or in "Related Searches if the keyword is obviously a question) section for the provided keyword.
get_keywords_site_structure
- Clustering endpoint. You can use it either in bulk (then provide a value for keywords) or in single request (then provide a value for keyword).
- Input:
  - keyword (string): Requested keyword. Ignored if keywords is provided. If you only provide a value for keyword (without keywords), then an equivalent of get_keywords_find will run first, to fetch keywords to group.
  - keywords (string[]): Requested keywords.
  - mode (string): Clustering mode. Either manual or multi. In manual mode, keywords are grouped based on SERP similarity. In multi mode, hierarchical groups are made, based on graph link density.
get_keywords_serp_compare
- Compares a given keyword/expression's SERP at 2 different dates.
- Inputs:
  - keyword (string): Requested keyword/expression.
  - period (string): The comparison period for SERPs (1 month, 3 months, 6 months, 12 months, custom).
  - first_date (string): Date in YYYY-MM-DD format. Ignored if period is not custom. This date must be a valid date for the given keyword/expression. Valid search dates are returned in available_search_dates item in call response, or as a response for get_keywords_serp_available_dates.
  - second_date (string): Date in YYYY-MM-DD format. Ignored if period is not custom. This date must be a valid date for the given keyword/expression. Valid search dates are returned in available_search_dates item in call response, or as a response for get_keywords_serp_available_dates.
get_keywords_serp_availableDates
- Retrieves the available dates for historical SERP data for a given keyword.
- Input:
  - keyword (string): Requested keyword.
get_keywords_serp_pageEvolution
- Retrieves the evolution of SERP rankings of a given URL for a specific keyword over time. All parameters are mandatory.
- Inputs:
  - keyword (string): Requested keyword/expression.
  - first_date (string): Date in YYYY-MM-DD format.
  - second_date (string): Date in YYYY-MM-DD format.
  - url (string): URL to track rankings for.
get_keywords_bulk
- Retrieves keyword data (SEO metrics, ads metrics, etc.) for multiple keywords at once in a bulk request.
- Input:
  - keywords (string[]): Array containing the requested keywords.
get_keywords_scrap
- Ask Haloscan to scrape the search engine results pages (SERP) for a given keyword/expression. The scrap will take around 24h to be completed.
- Input:
  - keywords (string[]): Array containing the requested keywords.

3. Site Explorer Tools

get_domains_overview
- Retrieves a comprehensive SEO performance summary for a specific domain.
- Inputs:
  - input (string): Target url, domain or root domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - requested_data (string[]): At least one of (metrics, positions_breakdown, traffic_value, categories, best_keywords, best_pages, gmb_backlinks, visibility_index_history, positions_breakdown_history, positions_and_pages_history). Which data to fetch among:
    - metrics: SEO metrics for the given domain (VI, position count, keyword count, traffic, page count, ranks, etc.).
    - positions_breakdown: Search engine ranking positions for the given domain.
    - traffic_value: Traffic value for the given domain (may take a while to compute for large domains).
    - categories: Categories for the given domain (may take a while to compute for large domains).
    - best_keywords: Top-performing keywords for the given domain (may take a while to compute for large domains).
    - best_pages: Top-performing pages for the given domain (may take a while to compute for large domains).
    - gmb_backlinks: GMB backlinks for the given domain.
    - visibility_index_history: Visibility index history for the given domain.
    - positions_breakdown_history: Search engine ranking positions breakdown history for the given domain.
    - positions_and_pages_history: Search engine ranking positions and pages history for the given domain.
get_domains_positions
- Retrieves the search engine ranking positions of a specified domain.
- Input:
  - input (string): Target url, domain or root domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
get_domains_top_pages
- Retrieves the top-performing pages of a specified domain based on aggregated organic search metrics such as traffic, number of ranking keywords.
- Input:
  - input (string): Target url, domain or root domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
get_domains_history_positions
- Retrieves historical ranking positions for a specific domain, between 2 specified dates. Very useful if you want to find lost positions.
- Inputs:
  - input (string): Target url or domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - date_from (string): Date in YYYY-MM-DD format.
  - date_to (string): Date in YYYY-MM-DD format.
get_domains_history_pages
- Retrieves page-wise historical SEO performance data for a specified domain between 2 specified dates.
- Inputs:
  - input (string): Target url or domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - date_from (string): Date in YYYY-MM-DD format.
  - date_to (string): Date in YYYY-MM-DD format.
get_page_best_keywords
- Retrieves the top-performing keywords for a specific URL, showing which search queries drive the most traffic and visibility to that page.
- Input:
  - input (string[]): Target urls.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - strategy (string): Any of (both, only_active, only_lost). Whether to return all positioned keywords, only active ones or only lost ones.
get_domains_keywords
- Retrieves current positions of a given domain for a list of given keywords.
- Inputs:
  - input (string): Target url or domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - keywords (string[]): Mandatory array containing the requested keywords.
get_domains_bulk
- Retrieves SEO performance metrics for multiple domains in a single request.
- Input:
  - inputs (string[]): Array containing the requested urls or domains.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domains.
get_domains_competitors
- Retrieves a list of organic search competitors for a given domain based on overlapping keywords (may take a while to compute for large domains).
- Input:
  - input (string): Target url or domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
get_domains_competitors_keywords_diff
- Compares the keyword differences between a given domain and its competitors, highlighting keywords that one domain ranks for but the other does not (may take a while to compute for large domains).
- Inputs:
  - input (string): Target url or domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - competitors (string[]): Mandatory list of (up to 20) competitors to compare the input to.
  - exclusive (boolean): Whether to include positions where only the search input is positioned, and none of the requested competitors is.
  - missing (boolean): Whether to include positions where the search input is not positioned, and at least one of the requested competitors is.
  - bested (boolean): Whether to include positions where the search input is positioned, and better positioned than at least one of the requested competitors.
  - besting (boolean): Whether to include positions where the search input is positioned, but at least one of the requested competitors is positioned better.
get_domains_competitors_best_pages
- Retrieves the best-performing pages of (specified) competitors of a given domain (may take a while to compute for large domains).
- Inputs:
  - input (string): Target url or domain.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - competitors (string[]): Mandatory list of (up to 20) competitors to compare the input to.
get_domains_competitors_keywords_best_positions
- Retrieves the best-ranking positions for a given list of domains on a given list of keywords.
- Inputs:
  - competitors (string[]): List of competitor domains or root domains.
  - keywords (string[]): Mandatory list of keywords to look for.
get_domains_visibility_trends
- Retrieves the visibility trend for a specific domain over time, showing how its search engine visibility has evolved.
- Input:
  - input (string[]): Array containing the requested urls or domains.
  - mode (string): Any of (auto, root, domain, url). How to interpret the input. Usually, you want to use root to get data about the root domain.
  - type (string): Any of (first, highest, trends, index). Should data be scaled, and how. Use index to get the raw visibility index.
get_domains_expired
- Returns a list of available domains. Domains are returned without their url unless you have already revealed them (in which case root_domain is filled), and a call to domains/expired/reveal is required to reveal domains you are interested in.
- Input:
  - keyword (string): Optional keyword on which the expired domain should have been positioned.

Configuration

Sign up for an Haloscan account.
Choose a plan.
Generate your API key from Configuration API page.
Use the API key for the Haloscan server in the Claude Desktop configuration file.

Usage with Claude Desktop

Add this server to your Claude Desktop configuration file claude_desktop_config.json:

NPX

{
  "mcpServers": {
    "haloscan": {
      "command": "npx",
      "args": [
        "-y",
        "@occirank/haloscan-server",
        "start"
      ],
      "env": {
        "HALOSCAN_API_KEY": "YOUR API KEY"
      }
    }
  }
}

License

MIT