Skip to main content
Glama
arsenkin-mcp

arsenkin-mcp

by zai-one

🇬🇧 English · 🇷🇺 Русский

Arsenkin MCP

Run your SEO checks in batches from your AI assistant.

MCP server for Arsenkin Tools: paid SEO batch jobs (SERP, clustering, Wordstat frequency, indexation, LSI, meta tags, AI answers) with estimate → approve → submit, plus free saved Projects data.

Collect SERPs, check keyword frequency, cluster queries or inspect indexation through Arsenkin Tools. The MCP server gives your assistant a workflow for estimating requests, getting approval, tracking jobs and working with saved results.

Quick start · Connect your assistant · Issues

Try asking your assistant:

Prepare a frequency-check batch for my keyword list. Show the request plan and estimated cost before submitting anything.

What you can do

Your task

What the MCP server provides

Research keywords

Keyword frequency, related phrases, demand trends, search suggestions and clustering.

Inspect search visibility

SERP, position, indexation and relevant-URL checks.

Manage a batch

Discover profiles, estimate, approve, submit, diagnose the worker and export saved results.

Read the result

URL/host occurrence tables and cluster records with source pointers, in JSON or CSV.

Review saved projects

arsenkin_projects reads your SEO projects through the Projects API: regions, competitors, keywords, groups, saved positions and visibility/top/average/median charts. It never starts a position check.

Check remaining limits

arsenkin_limits returns the account's total and spent limits before you prepare paid tasks.

Saved-result examples and worker help show how to turn a completed SEO task into a useful table.

Related MCP server: DataForSEO MCP Server

Why this MCP

  • Optional lazy tool loading: set ARSENKIN_TOOL_LOADING=lazy (or choose it in the setup wizard) to start with a small core and enable toolsets on demand; see Lazy tool loading.

  • Every paid job is estimated first, budget-checked and submitted only after approval (exception: the opt-in projects run_positions, see below); arsenkin_limits shows remaining limits.

  • Jobs run through a worker with tracked state; results are saved and exported as tables (JSON/CSV) with source pointers.

  • 18 default tools (meta, jobs, results, projects) plus opt-in projects_write, 4 prompts, guide resources and skills.

  • We found no other Arsenkin Tools MCP server on GitHub (search on 2026-10-13).

Lazy tool loading

Optional lazy tool loading: ARSENKIN_TOOL_LOADING=lazy starts with a small core plus arsenkin_enable_toolsets and adds toolsets on demand (tools/list_changed). Startup cost (tools/list + instructions, ≈chars/4): eager ≈3678 tokens, lazy ≈1285 tokens (−65%). Default eager is unchanged; if your client ignores tools/list_changed, keep eager or reconnect after enabling. Scope: enablement is per MCP session (FastMCP session visibility), so one client's enabled toolsets never appear for another. The HTTP transport here is stateless (every request is its own session), so enabled toolsets do not persist there: for shared HTTP use eager or ARSENKIN_TOOLSETS.

Clients and notifications/tools/list_changed (verified against official docs, changelogs or maintainer statements, 2026-10):

Client

tools/list_changed

Source

Claude Code

Supported (interactive: tools, prompts, resources; -p/Agent SDK: tools)

docs: Dynamic tool updates

VS Code (GitHub Copilot)

Supported (dynamic tool discovery); new tools may reach the agent only on the next turn

docs, #303012

Gemini CLI

Supported (refreshes the tool registry)

PR #14375, PR #21050

Cursor

Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling

forum

Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue

Unverified: no official statement found; use eager or reconnect after enabling

—

Maintained and up to date

  • Actively maintained by ZAI.ONE: current version 0.6.0; release notes in CHANGELOG.md and Releases.

  • Built-in update check: ask the assistant to run arsenkin_check_update (public GitHub API, no credentials, cached; nothing is installed automatically; ARSENKIN_DISABLE_UPDATE_CHECK=1 turns it off).

  • Follows current MCP practice: tool annotations (read-only / destructive hints), toolsets and read-only mode, server instructions, prompts and resources, structured errors with recovery hints, secrets kept out of tool output, a token budget for tool descriptions enforced in tests.

  • CI runs the test suite on Linux and Windows for every pull request.

Quick start

Prefer a ready package? Install the release and generate your client configuration. No source checkout is required.

Install Python 3.12–3.14 and uv. Clone with Git or download the ZIP. With a ZIP, open the extracted directory and skip the first two commands.

Have your Arsenkin API token ready for the configuration wizard. Start with a local request estimate, as shown below; enable paid execution after reviewing the access and limits section.

git clone https://github.com/zai-one/arsenkin-mcp.git
cd arsenkin-mcp
uv sync --frozen --extra standalone
uv run --frozen --extra standalone python scripts/configure.py
uv run --frozen --extra standalone arsenkin-mcp --config mcp.local.json --check-config

The wizard creates a local configuration and stores secrets in private files. It refuses to overwrite an existing setup. --check-config validates local settings; use arsenkin_status separately to check account connectivity.

Connect your assistant

Add this configuration to an MCP client that uses mcpServers, such as Claude Desktop or Cursor. Replace /ABSOLUTE/PATH/ with your absolute path; Windows JSON paths can use forward slashes, such as D:/Tools/.

{
  "mcpServers": {
    "arsenkin": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/arsenkin-mcp",
        "run",
        "--frozen",
        "--extra",
        "standalone",
        "arsenkin-mcp",
        "--config",
        "/ABSOLUTE/PATH/arsenkin-mcp/mcp.local.json"
      ]
    }
  }
}

The client starts the MCP server for you. Refresh its tool list, then make your first request. For clients with a different config format, reuse the same command and args; uv must be available to the client process.

First request

Prepare an estimate for a frequency-check request with one phrase. Ask me for the region and frequency type; do not submit a paid job.

An estimate validates the request locally and shows the server cost estimate without calling Arsenkin. Submitting a paid job is a separate step. Cost estimates use configured policy units, not a guaranteed invoice amount or a ruble quote.

If tools do not appear, check the absolute path, whether the client can find uv, and the --check-config result. For access errors, check account credentials and permissions. Installation and troubleshooting.

Install in your agent

Run arsenkin-mcp straight from GitHub with uv. Pin a release tag (@vX.Y.Z) for reproducible installs; placeholders below are examples, keep secrets in files outside the repo.

Claude Code

claude mcp add arsenkin --env ARSENKIN_TOKEN_FILE=/path/to/arsenkin.token --env ARSENKIN_STATE_PATH=/path/to/arsenkin.sqlite -- uvx --from git+https://github.com/zai-one/arsenkin-mcp@v0.6.0 arsenkin-mcp

Skills for Claude Code: copy skills/* into ~/.claude/skills/ (or install this repo as a plugin — it ships .claude-plugin/plugin.json with the skills and the MCP server).

Cursor — .cursor/mcp.json (one-click install):

{
  "mcpServers": {
    "arsenkin": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zai-one/arsenkin-mcp@v0.6.0",
        "arsenkin-mcp"
      ],
      "env": {
        "ARSENKIN_TOKEN_FILE": "/path/to/arsenkin.token",
        "ARSENKIN_STATE_PATH": "/path/to/arsenkin.sqlite"
      }
    }
  }
}

Codex — ~/.codex/config.toml (skills: copy skills/* into ~/.codex/skills/, or keep the repo's .agents/skills link):

[mcp_servers.arsenkin]
command = "uvx"
args = ["--from", "git+https://github.com/zai-one/arsenkin-mcp@v0.6.0", "arsenkin-mcp"]
env = { ARSENKIN_TOKEN_FILE = "/path/to/arsenkin.token", ARSENKIN_STATE_PATH = "/path/to/arsenkin.sqlite" }

Claude Desktop — claude_desktop_config.json: the same mcpServers block as Cursor.

Skills (agent playbooks)

Each skill is a self-contained folder skills/<name>/ (SKILL.md + its own references/, templates/); copy the folder and it works. Agents load the short SKILL.md only when the task matches and open the other files on demand. Clients without skills get the same flows as MCP prompts and the arsenkin://playbook / arsenkin://guide/{topic} resources.

Skill

What it does

arsenkin-serp-clustering

Cluster keywords by SERP overlap: estimate, approval, submit, poll, clusters table.

arsenkin-index-check

Yandex/Google indexation of URLs with a non-indexed report.

arsenkin-text-relevance

LSI/highlights, Title/H1 of the TOP vs your page, optional copywriting brief.

arsenkin-semantic-core

Semantics -> clusters -> positions: Wordstat phrases/frequency, clustering, project groups and a position check.

Toolsets and read-only mode

Default: meta, jobs, results, projects. Opt-in projects_write (arsenkin_projects_write: create/update/delete projects, groups and tags, add/delete regions, competitors and keywords, restore_keywords, tag/untag groups and keywords, run a paid position check — the latter also needs the operator setting ARSENKIN_PROJECTS_PAID=on; run_positions is not counted against the ARSENKIN monthly budgets or ARSENKIN_MAX_COST_PER_APPROVAL and has no cost estimate: its only gates are that setting and the operator approval). Free preview until confirm=true; then every write returns an approval_id and operator_command; the operator reviews the exact request with arsenkin-projects-approval --path FILE --list and accepts it outside MCP with the returned arsenkin-projects-approval --path FILE --approval-id ID --digest D --accept (single use, request-bound, bound to the preparing principal and account, 30 min; at most 10 waiting per principal) before the agent repeats the call with approval_id. If a write was sent but its result is unknown (code: outcome_unknown), do not retry: check with arsenkin_projects, then the operator runs arsenkin-projects-approval --path FILE --approval-id ID --resolve applied|not_applied. ARSENKIN_TOOLSETS=default, all or a comma list (see arsenkin://toolsets); ARSENKIN_TOOLS=a,b adds single tools, ARSENKIN_DISABLED_TOOLS=a,b removes them, ARSENKIN_READ_ONLY=1 removes every write/paid tool.

Example requests

  • Сколько лимитов Arsenkin осталось?

  • Кластеризуй этот список запросов для Москвы — сначала покажи стоимость.

  • Проверь индексацию этих URL в Яндексе и Google.

  • Что ТОП ожидает в тексте по запросу «ремонт киа»?

  • Покажи сохранённые позиции проекта за месяц.

  • Выгрузи результат задачи в CSV.

Access and limits

For execution, configure paid-task limits and approval, then run the worker with the same config and SQLite state. Exported values keep their JSON paths; specialised SEO tables are not generated automatically. Cancelling a job does not guarantee a refund for work already submitted.

Updates

arsenkin_check_update compares the installed version with the latest GitHub release and returns the release link and the matching uv tool install --force ... command. It never installs anything and spends no Arsenkin limits. The result is cached for 24 hours next to the state database; when a newer release is cached, the server instructions and arsenkin_local_diagnostics mention it. Set ARSENKIN_DISABLE_UPDATE_CHECK=1 to turn off both the tool's network request and the startup refresh.

Authenticated HTTP is available for a server deployment. See HTTP setup, configuration and permissions and Python package integration.

uv sync --frozen --all-groups --extra standalone
uv run --frozen --extra standalone python scripts/verify.py
uv run --frozen --extra standalone python scripts/verify_install.py

Tests use synthetic fixtures. A passing test run does not establish live provider connectivity.

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

License, use and contributing

  • Use: you may install and use this MCP server freely for yourself and your organisation, including commercial work. If it helps, please consider giving the repository a ⭐ — appreciated, never required.

  • Contribute: issues and pull requests are welcome; see CONTRIBUTING.md. Never post tokens, cookies, sessions or account data.

  • Not allowed without written permission from ZAI.ONE: copying code into other projects, forking for redistribution, embedding the server in other products or offering it as a competing service.

  • License: LicenseRef-ZAI-ONE 2.0 (source-available, not open source). Third-party notices and license history: NOTICE.

Available Tools

18 tools
arsenkin_batch_estimateArsenkin: batch estimateA
Read-onlyIdempotent

Plan, coalesce and price a multi-request batch. Use before arsenkin_batch_prepare. Cost: free, no provider call.

Inputs: requests (required). Returns: object

arsenkin_batch_prepareArsenkin: batch prepareA

Create one bounded approval for a batch. Use after arsenkin_batch_estimate; then arsenkin_batch_submit. Writes: approval record only, no spend.

Inputs: requests (required). Returns: object

arsenkin_batch_submitArsenkin: batch submitA
DestructiveIdempotent

Queue an approved batch job; the worker coalesces and polls. Use after explicit OK; poll arsenkin_task_status. Cost: spends Arsenkin limits (see estimate); requires approval_id from arsenkin_prepare.

Inputs: requests (required), approval_id (required), idempotency_key (required). Returns: object

arsenkin_cancelArsenkin: cancelA
DestructiveIdempotent

Request cancellation of your queued/running job. Use when the user aborts; already spent limits may not return.

Inputs: job_id (required). Returns: object

arsenkin_check_updateArsenkin: check updateA
Read-onlyIdempotent

Check for a newer server release; never installs. Cost: free, 24h cache.

Inputs: force_refresh. Returns: object

arsenkin_estimateArsenkin: estimateA
Read-onlyIdempotent

Validate one job payload and estimate its cost. Use before arsenkin_prepare; for many payloads use arsenkin_batch_estimate. Cost: free, no provider call.

Inputs: payload (required), profile (required). Returns: object

arsenkin_export_resultArsenkin: export resultA
Read-onlyIdempotent

Export a saved job as bounded JSONL/CSV with provenance. Use for spreadsheets/files. Cost: free, no provider call.

Inputs: job_id (required), format, max_rows. Returns: object

arsenkin_get_resultArsenkin: get resultA
Read-onlyIdempotent

Return the stored result of your job (can be large). Use for small jobs; for compact tables use arsenkin_result_table, for files arsenkin_export_result. Cost: free.

Inputs: job_id (required). Returns: object

arsenkin_limitsArsenkin: limitsA
Read-onlyIdempotent

Read total and spent Arsenkin limits. Use before prepare/submit to show what is left. Cost: free.

Inputs: no named parameters. Returns: object

arsenkin_local_diagnosticsArsenkin: local diagnosticsA
Read-onlyIdempotent

Explain local worker heartbeat, your queue and budget. Use when jobs stay queued. Cost: free, no provider call.

Inputs: no named parameters. Returns: object

arsenkin_prepareArsenkin: prepareA

Create a bounded approval for one paid job. Use after the user saw the estimate; then arsenkin_submit. Writes: approval record only, no spend.

Inputs: payload (required), profile (required). Returns: object

arsenkin_profile_catalogArsenkin: profile catalogA
Read-onlyIdempotent

List job profiles, payload fields and examples. Use first to build a payload; which profile when: arsenkin://guide/tools. Cost: free, no provider call.

Inputs: no named parameters. Returns: object

arsenkin_projectsArsenkin: projectsA
Read-onlyIdempotent

Read saved Arsenkin Projects data: projects, regions, competitors, keywords, saved positions, charts. Use for tracked-project reports; never starts checks. Cost: free.

Inputs: report (required), name, page, sort, +22 more. Returns: object

arsenkin_request_hash_lookupArsenkin: request hash lookupA
Read-onlyIdempotent

Look up whether an identical request is already in the ledger. Use before resubmitting after an unknown outcome. Cost: free.

Inputs: request_hashes (required). Returns: object

arsenkin_result_tableArsenkin: result tableA
Read-onlyIdempotent

Build compact SERP URL/host frequency or cluster tables from a saved result. Use for reports instead of raw results. Cost: free, no new paid calls.

Inputs: view (required), job_id (required), format, max_rows, +1 more. Returns: object

arsenkin_statusArsenkin: statusA
Read-onlyIdempotent

Check Arsenkin account/API availability. Use when jobs fail; for limits use arsenkin_limits. Cost: free.

Inputs: no named parameters. Returns: object

arsenkin_submitArsenkin: submitA
DestructiveIdempotent

Queue an approved paid job; returns job_id without waiting. Use only after the user's explicit OK; poll arsenkin_task_status. Cost: spends Arsenkin limits (see estimate); requires approval_id from arsenkin_prepare.

Inputs: payload (required), profile (required), approval_id (required), idempotency_key (required). Returns: object

arsenkin_task_statusArsenkin: task statusA
Read-onlyIdempotent

Read durable status of your job. Use to poll after submit; when done use arsenkin_get_result or arsenkin_result_table. Cost: free.

Inputs: job_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 18 tools

    Disambiguation4/5

    The single vs batch variants (estimate/batch_estimate, prepare/batch_prepare, submit/batch_submit) are clearly paired and differentiated by scope, and descriptions explicitly state 'which when' and ordering. arsenkin_status vs arsenkin_task_status and get_result vs result_table vs export_result could momentarily overlap, but descriptions clearly separate account health, job polling, raw results, compact tables, and file export.

    Naming Consistency4/5

    All names use the arsenkin_ prefix and snake_case throughout, with consistent verb_noun forms (get_result, batch_estimate, check_update, request_hash_lookup). There is minor variance between bare nouns (projects, limits, status) and verb-led names, but the pattern is predictable and readable.

    Tool Count4/5

    18 tools is slightly heavy but justified by the full paid-job lifecycle (discover, estimate, approve, submit, poll, fetch, export, cancel) with mirrored single/batch pairs. Each tool has a distinct stage or purpose, so few feel redundant.

    Completeness4/5

    The surface covers the lifecycle end-to-end: catalog, estimate, approval, submit, poll, result retrieval/table/export, limits, diagnostics, ledger lookup, and cancellation. Minor gaps like listing all prior jobs or re-running a saved job are largely workable via task_status and projects.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      D
      maintenance
      Enables LLMs to interact with DataForSEO and other SEO APIs through natural language, allowing for keyword research, SERP analysis, backlink analysis, and local SEO tasks.
      100
      83
      MIT
    • A
      license
      C
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with DataForSEO APIs and obtain SEO data including SERP results, keyword research, on-page metrics, backlink analysis, and domain analytics through a standardized interface.
      76
      10,352 npm
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables professional SEO/SEM research with geolocalized keyword discovery, competitor analysis, and SERP ranking insights using DataForSEO API.
      -
    • F
      license
      B
      quality
      D
      maintenance
      Enables SEO analysis and data retrieval through DataForSEO API, including keyword research, backlinks, competitor analysis, and on-page audits.
      2
      24
      -