@cododel/yandex-wordstat-mcp

Bun/TypeScript MCP server for the official Yandex Wordstat v2 API. It provides the same practical Wordstat surface as the upstream yandex-wordstat-mcp package and adds a shared typed architecture, local stdio and stateless Streamable HTTP transports, remote BYOK credentials, explicit server-owned credential opt-in, Docker packaging, cost metadata, and generic agent installation guidance.

Commands

# Local MCP child process; requires Yandex credentials in ENV
bun src/cli.ts stdio

# Remote stateless Streamable HTTP; BYOK headers required by default
bun src/cli.ts serve --host 127.0.0.1 --port 3000

See INSTALL.md for MCP client, Docker, authentication, and upgrade instructions.

Tools

Tool	Wordstat method	Billing
get-regions-tree	GetRegionsTree	free
get-region-children	cached GetRegionsTree	free
top-requests	GetTop	~0.02 RUB/call
dynamics	GetDynamics	~0.02 RUB/call
regions	GetRegionsDistribution	~0.05 RUB/call

Pricing is informational and can change. Source: Yandex Search API pricing.

Local credentials

Accepted aliases, in priority order:

YANDEX_WORDSTAT_API_KEY or YANDEX_SEARCH_API_KEY
YANDEX_WORDSTAT_FOLDER_ID or YANDEX_CLOUD_FOLDER_ID or YANDEX_FOLDER_ID

Remote credential policy

Default serve behavior:

• server ENV Yandex credentials are ignored;
• every MCP request needs X-Yandex-API-Key and X-Yandex-Folder-Id;
• keys are transport headers and are absent from tool schemas;
• loopback BYOK may omit MCP_ACCESS_TOKEN, but non-loopback HTTP requires it;
• --allow-server-credentials always requires a non-empty MCP_ACCESS_TOKEN;
• browser Origin and Host checks run before credential handling;
• server credentials become available only with --allow-server-credentials.

Serve behind HTTPS. The built-in server intentionally does not terminate TLS.

Billing safety and exact counts

• top-requests, dynamics, and regions are at-most-once billed operations. Clients must not retry them automatically after errors or unknown outcomes.
• Set WORDSTAT_MAX_COST_RUB_PER_HOUR and WORDSTAT_MAX_COST_RUB_PER_DAY together to enable a persistent SQLite budget guard. Amounts are parsed to integer kopecks; every dispatched paid attempt counts conservatively.
• WORDSTAT_LEDGER_PATH defaults to ./data/wordstat.sqlite; Docker uses the persistent /data/wordstat.sqlite volume.
• Wordstat int64 count fields are returned as exact decimal strings, not JSON numbers.

Development

bun install --frozen-lockfile
bun test
bun run typecheck

The project uses native Bun TypeScript. There is no emitted dist/ directory.

Attribution

This project uses the MIT-licensed packages/yandex-wordstat-mcp implementation by Alternex as its functional baseline. See UPSTREAM.md and LICENSE.