bukvarix-mcp

MCP server for the Bukvarix API — keyword research and domain analysis for the Russian-language search market (Yandex / Google).

Exposes 5 tools that map 1:1 onto Bukvarix's HTTP endpoints, handling percent-encoding, BOM stripping, and error surfacing for you. Works out of the box with the free API key (api_key=free).

Tools

Tool	Endpoint	Description
bukvarix_keywords	GET /v1/keywords/	Simple keyword search by a single phrase
bukvarix_mkeywords	POST /v1/mkeywords/	Extended search by a list (up to 100 phrases + 250 exclusions on free)
bukvarix_site	GET /v1/site/	Keywords for a single domain
bukvarix_site_cmp	GET /v1/site_cmp/	Compare two domains (intersect / domain1_uniq / domain2_uniq)
bukvarix_site_mcmp	POST /v1/site_mcmp/	Compare 3–10 domains

Common parameters

• q — phrase, domain, or newline-separated list
• q2 — second domain, or exclusion list (for mkeywords / site_cmp)
• num — row count (default 250, max 1,000,000 on free)
• format — json (default) / txt / csv / tsv
• region — domains only: msk (default, Yandex Moscow), gmsk (Google Moscow), spb, rus, nsk, ekb, kzn, nnv, kry, che, sam, ufa, rnd, krr, oms, vrn, prm, vlg, sar, tmn, tom, gkiev, minsk, gminsk, nursul
• comparison_type — site_cmp only: intersect (default) / domain1_uniq / domain2_uniq
• result_count — return only the total count
• api_key — per-call override; otherwise BUKVARIX_API_KEY env (defaults to free)

Query syntax (keywords)

Bukvarix supports operators (percent-encoded automatically):

• строител* товары — wildcard
• !пластиковые !окна — exact match

See query_syntax.html#modifiers.

Free tier limits

• num up to 1,000,000; default 250
• mkeywords: q ≤ 100 phrases, q2 ≤ 250 (101+ ignored)
• site_mcmp: ≤ 10 domains
• Filters broad_from/to, exact_from/to, length_from/to, words_from/to — paid only (402 on free)
• 429 = rate limit, pause and retry. Alternatively download full bases from /about_bases.html.

Installation

git clone https://github.com/frankydzoro/bukvarix-mcp.git
cd bukvarix-mcp
npm install

Usage with Hermes

Add to ~/.hermes/config.yaml:

mcp_servers:
  bukvarix:
    command: node
    args: [/absolute/path/to/bukvarix-mcp/src/index.js]
    enabled: true
    env:
      BUKVARIX_API_KEY: free   # or your paid key

Verify:

hermes mcp test bukvarix

Generic MCP config (e.g. Claude Desktop):

{
  "mcpServers": {
    "bukvarix": {
      "command": "node",
      "args": ["/absolute/path/to/bukvarix-mcp/src/index.js"],
      "env": { "BUKVARIX_API_KEY": "free" }
    }
  }
}

License

MIT