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