Keyword Insights MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Keyword Insights API.

Features

• 23 tools covering all Keyword Insights API endpoints
• Automatic authentication with token caching
• Async HTTP client for optimal performance
• Full support for keyword clustering, ranking, content briefs, and writer agent
• Pagination support for large result sets
• Explicit parameter schemas for better AI model understanding
• Compact responses - ~70% smaller output (no whitespace, nulls/empties stripped)

Installation

Option 1: Using uvx (Recommended)

No installation required - uvx runs the package in an isolated environment:

uvx keyword-insights-mcp

If you don't have uv installed, get it from astral.sh/uv.

Option 2: Using pip

pip install keyword-insights-mcp

Note: If you have multiple Python versions installed, ensure you install with the same Python that will run the server. Use python -m pip install keyword-insights-mcp to be explicit.

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

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

Using uvx (Recommended)

{
  "mcpServers": {
    "keyword-insights": {
      "command": "uvx",
      "args": ["keyword-insights-mcp"],
      "env": {
        "KEYWORD_INSIGHTS_EMAIL": "your-email@example.com",
        "KEYWORD_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

Using pip installation

{
  "mcpServers": {
    "keyword-insights": {
      "command": "python",
      "args": ["-m", "keyword_insights_mcp.server"],
      "env": {
        "KEYWORD_INSIGHTS_EMAIL": "your-email@example.com",
        "KEYWORD_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

With Claude Code

Add to your project's .mcp.json or Claude Code settings:

Using uvx (Recommended)

{
  "mcpServers": {
    "keyword-insights": {
      "command": "uvx",
      "args": ["keyword-insights-mcp"],
      "env": {
        "KEYWORD_INSIGHTS_EMAIL": "your-email@example.com",
        "KEYWORD_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

Using pip installation

{
  "mcpServers": {
    "keyword-insights": {
      "command": "python",
      "args": ["-m", "keyword_insights_mcp.server"],
      "env": {
        "KEYWORD_INSIGHTS_EMAIL": "your-email@example.com",
        "KEYWORD_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

Testing with MCP Inspector

mcp dev src/keyword_insights_mcp/server.py

Available Tools

User

• get_user - Get account data, credit balance, and subscription info

Keyword Ranking

• create_advanced_ranking_order - Analyze SERP for a single keyword
  • Required: keyword, location, language
  • Optional: device, domain, include_word_count
• get_advanced_ranking_order - Get ranking order results
• create_advanced_ranking_batch_order - Analyze SERP for multiple keywords
• get_advanced_ranking_batch_order - Get batch ranking results

Content Brief

• get_content_brief_languages - List supported languages
• create_content_brief - Create a content brief from SERP analysis
  • Required: keyword, language, location
• get_content_brief - Get brief results by brief_id
• list_content_briefs - List all briefs

Keyword Content

• create_keyword_content_order - Extract content insights (PAA, Reddit/Quora questions, meta titles/descriptions)
  • Required: keyword, language, location, content_insights
  • Optional: device
  • Credit costs: paa/reddit/quora = 50 credits, meta_titles/descriptions = 200 credits each
• get_keyword_content_order - Get content order results

Keyword Insights (Clustering)

• get_insights_languages - List supported languages
• get_insights_locations - List locations (returns first 20 by default)
• search_insights_locations - Search locations by name (recommended)
• create_insights_order - Create keyword clustering order
  • Required: project_name, keywords, search_volumes, language, location, insights
  • Optional: clustering_method, grouping_accuracy, hub_creation_method, device, url, folder_id
  • Insights options: cluster, context, rank, title_ai
• get_insights_order - Get clustering order status/results
• get_insights_order_cost - Estimate order cost before creating
  • Required: n_keywords, insights
• get_insights_order_json - Get clustered data with pagination
  • Required: order_id
  • Optional: page_size (default 50), page_number, sort_by, ascending
• export_insights_order_xlsx - Export to Excel file
• list_insights_orders - List orders by count or date range

Writer Agent

• get_writer_agent_options - Get available content types, tones, and POV options
• create_writer_agent_order - Generate AI article outline, plan, and content
  • Required: keyword
  • Optional: language_code, location_name, content_type, point_of_view, folder_id, additional_insights
• get_writer_agent_order - Get generated content results

Example Usage

Once configured, you can ask Claude to:

• "Get my Keyword Insights account balance"
• "Search for locations matching 'Mexico'"
• "Estimate the cost of clustering 500 keywords with cluster and context insights"
• "Create a keyword insights order for these keywords with their search volumes"
• "Get page 2 of the clustered results for order abc123"
• "Create a content brief for 'best running shoes' in English for the United States"
• "Generate an article about 'sustainable gardening tips'"

License

MIT