XiaoFlow MCP Server

Official MCP server for XiaoFlow AI SEO Tools and Etsy Market Intelligence

文件

XiaoFlow MCP Server (`xiaoflow-mcp-server`)

Official Model Context Protocol (MCP) server for XiaoFlow AI SEO and keyword intelligence tools.

Connect Large Language Models (LLMs) such as Claude Desktop, Cursor, Windsurf, and VS Code directly to XiaoFlow's search engine optimization, keyword discovery, and domain analytics.

Remote endpoint: https://mcp.xiaoflow.com/mcp

Transport: MCP Streamable HTTP with OAuth 2.1 / PKCE, plus stdio through the npm package

Safety: Read-only research tools, except asynchronous expansion task creation; no destructive tools

Official listings

✨ Features & Capabilities

🔍 Keyword Discovery: Generate high-intent search keywords and SEO ideas from keyword, URL, or domain seeds.
📊 Domain Analytics: Analyze domain-level search performance, organic traffic metrics, and keyword distributions.
📈 Search Trend Analysis: Compare keyword demand, competition, CPC, and historical trends.
🔒 Flexible Authentication: Supports API Key authentication via query parameters (?key=), Bearer tokens, environment variables, or Web OAuth login.

⚡ Quick Start

1. Run via `npx` (stdio)

Run the server directly using npx:

npx -y xiaoflow-mcp-server

Pass your XiaoFlow API key via environment variable:

XIAOFLOW_API_KEY="YOUR_API_KEY" npx -y xiaoflow-mcp-server

2. Connect via Streamable HTTP with web login (recommended)

Use the canonical remote endpoint in clients that support remote MCP. The client discovers XiaoFlow OAuth automatically and opens the browser for login and consent:

https://mcp.xiaoflow.com/mcp

Legacy clients can still use https://mcp.xiaoflow.com/sse?key=YOUR_API_KEY.

💻 Client Integration Guides

Cursor Setup

Add XiaoFlow MCP to Cursor:

Name: xiaoflow
Type: http
URL: https://mcp.xiaoflow.com/mcp

Or click Add to Cursor directly on the XiaoFlow MCP Portal.

Claude Desktop Setup

Add the following entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "xiaoflow": {
      "command": "npx",
      "args": ["-y", "xiaoflow-mcp-server"],
      "env": {
        "XIAOFLOW_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf, VS Code, and other remote clients

Use native HTTP configuration where available:

{
  "mcpServers": {
    "xiaoflow": {
      "type": "http",
      "url": "https://mcp.xiaoflow.com/mcp"
    }
  }
}

For stdio-only clients, bridge to the OAuth-enabled remote endpoint:

{
  "mcpServers": {
    "xiaoflow": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.xiaoflow.com/mcp"]
    }
  }
}

🛠️ Available MCP Tools

MCP Tool	Description	Key Input Parameters
`get_keyword_metrics`	Exact metrics and monthly history for one keyword	`keyword`, `history_months` (1–48), `location`, `language`
`get_related_keywords`	Related keywords with metrics/history and unlimited pagination	`seed`, `history_months`, `page`, `page_size` (max 1,000)
`bulk_keyword_metrics`	Exact metrics/history for up to 1,000 keywords	`keywords`, `history_months`, `location`, `language`
`start_keyword_expansion`	Start round-based expansion from one or more seeds	`seeds`, `max_iterations`, include/exclude rules
`get_keyword_expansion_status`	Poll an expansion task and retrieve results	`task_id`, `include_results`
`analyze_url`	Analyze page or domain search visibility	`url`, `site`, `brand`, `location`, `language`
`get_domain_stats`	Overview search metrics & traffic trends for a domain	`domain`, `brand` (required: `0`=domain, `1`=brand)
`list_domain_keywords`	Retrieve paginated list of domain keywords	`domain`, `brand`, `page`, `page_size`
`get_keyword_details`	Retrieve keyword metrics for a 12, 24, or 48 month window	`slug`, `time_range`, `location`, `language`
`discover_keywords`	Backward-compatible related keyword discovery	`keyword`, `url`, `site`, `location`, `language`
`bulk_keyword_lookup`	Backward-compatible bulk metrics lookup	`keywords`, `location`, `language`

Legacy aliases remain available for backward compatibility.

Every tool publishes:

descriptions for every input parameter;
a named JSON output schema, including success and error fields;
MCP safety annotations (readOnlyHint, destructiveHint, idempotentHint, and openWorldHint);
a human-readable tool title for MCP clients and directories.

Example prompts

Get US English metrics and 24 months of history for "AI SEO tools".

Find every related keyword for "standing desk", 200 per page, and continue
until has_more is false. Return search volume, CPC, competition, intent, and history.

Compare these 1,000 keywords over 48 months and rank them by search volume growth.

Expand "home office" for four rounds, keep terms with at least 100 monthly
searches, and poll the task until it is complete.

🔑 Authentication

Obtain your API key from the XiaoFlow MCP Dashboard.

Supported authentication methods:

Web Login OAuth (recommended): connect to https://mcp.xiaoflow.com/mcp; compatible clients discover OAuth, PKCE, and dynamic client registration automatically.
Environment Variable: set XIAOFLOW_API_KEY when running via npx.
Authorization Header: send Authorization: Bearer YOUR_API_KEY.
Legacy Query Parameter: append ?key=YOUR_API_KEY to the legacy SSE URL.

🐳 Docker / Glama

The repository includes a production multi-stage Dockerfile for directory build verification and stdio deployment:

docker build -t xiaoflow-mcp .
docker run --rm -i \
  -e XIAOFLOW_API_KEY="YOUR_API_KEY" \
  xiaoflow-mcp

The image runs as the unprivileged Node user, excludes local secrets and build state, and writes MCP protocol messages only to stdout.

🔐 Security and data handling

OAuth login occurs only on www.xiaoflow.com; MCP clients never receive your password.
API keys and OAuth tokens are sent only to the configured XiaoFlow API endpoint.
The server does not scan or upload project files.
Tool calls query external XiaoFlow/Google Ads-backed data and may consume account credits.
No tool deletes or modifies keyword or domain data.

Report vulnerabilities privately through the repository owner or the XiaoFlow contact page. Do not include tokens or customer data in public issues.

✅ Quality and compatibility

MCP protocol: Streamable HTTP and stdio
Authentication: OAuth 2.1 with PKCE, Bearer API key
Tool schemas: parameter descriptions, structured output schemas, annotations
Optional discovery methods: resources and prompts return valid empty lists
Runtime: Node.js 18+ (node:20-alpine in Docker)
Continuous endpoint: https://mcp.xiaoflow.com/mcp