# bukvarix-mcp

MCP server for the [Bukvarix API](https://www.bukvarix.com/api.html) — 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](https://www.bukvarix.com/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](https://www.bukvarix.com/about_bases.html).

## Installation

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

## Usage with Hermes

Add to `~/.hermes/config.yaml`:

```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:

```bash
hermes mcp test bukvarix
```

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

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

## License

MIT