arsenkin-mcp
This MCP server lets an AI assistant run Arsenkin SEO batch workflows end-to-end: plan and estimate requests, get approval, submit paid jobs, monitor them, and turn saved results into tables or exports.
Research keywords: keyword frequency, related phrases, demand trends, search suggestions, and clustering.
Inspect search visibility: SERP, position, indexation, and relevant-URL checks.
List supported profiles: discover available profiles, payload fields, and example SEO requests with
arsenkin_profile_catalog.Estimate costs without live calls: validate a single payload (
arsenkin_estimate) or plan/coalesce a batch (arsenkin_batch_estimate).Check account/API status: verify connectivity without submitting paid tasks (
arsenkin_status).Explain local worker state: heartbeat, queue, and configured budget via
arsenkin_local_diagnostics.Look up request hashes: check server-ledger hashes without exposing payload data.
Prepare approvals: create bounded approval for single (
arsenkin_prepare) or batch (arsenkin_batch_prepare) requests; may be accepted server-side by trusted policy.Submit approved jobs: queue paid requests (
arsenkin_submit,arsenkin_batch_submit) with idempotency keys; worker coalesces and polls centrally.Track jobs: get durable status (
arsenkin_task_status) or request cancellation (arsenkin_cancel).Read results: retrieve saved results (
arsenkin_get_result), export as JSONL/CSV with provenance (arsenkin_export_result), or build SERP/cluster tables (arsenkin_result_table).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@arsenkin-mcp Submit a backlink audit job for example.com and export results as CSV."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🇬🇧 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 |
|
Check remaining limits |
|
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_limitsshows 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 |
| Source |
Claude Code | Supported (interactive: tools, prompts, resources; | |
VS Code (GitHub Copilot) | Supported (dynamic tool discovery); new tools may reach the agent only on the next turn | |
Gemini CLI | Supported (refreshes the tool registry) | |
Cursor | Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling | |
Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue | Unverified: no official statement found; use | — |
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=1turns 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-configThe 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-mcpSkills 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 |
| Cluster keywords by SERP overlap: estimate, approval, submit, poll, clusters table. |
| Yandex/Google indexation of URLs with a non-indexed report. |
| LSI/highlights, Title/H1 of the TOP vs your page, optional copywriting brief. |
| 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.pyTests 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 toolsarsenkin_batch_estimateArsenkin: batch estimateARead-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 submitADestructiveIdempotent
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: cancelADestructiveIdempotent
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 updateARead-onlyIdempotent
Check for a newer server release; never installs. Cost: free, 24h cache.
Inputs: force_refresh. Returns: object
arsenkin_estimateArsenkin: estimateARead-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 resultARead-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 resultARead-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: limitsARead-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 diagnosticsARead-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 catalogARead-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: projectsARead-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 lookupARead-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 tableARead-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: statusARead-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: submitADestructiveIdempotent
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 statusARead-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
Scored across 18 tools
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.
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.
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.
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
Related MCP Connectors
Track keyword positions over time: create trackers, check ranks, and pull history programmatically.
Audit, rank-track and analyze SEO for sites via an authenticated MCP server.
Live SEO intelligence, rank tracking, site audits, and backlink analysis for AI agents.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Related MCP Servers
- AlicenseDqualityDmaintenanceEnables LLMs to interact with DataForSEO and other SEO APIs through natural language, allowing for keyword research, SERP analysis, backlink analysis, and local SEO tasks.10083MIT
- AlicenseCqualityNot gradedmaintenanceEnables 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.7610,352 npm-
- FlicenseNot gradedqualityDmaintenanceEnables professional SEO/SEM research with geolocalized keyword discovery, competitor analysis, and SERP ranking insights using DataForSEO API.-
- FlicenseBqualityDmaintenanceEnables SEO analysis and data retrieval through DataForSEO API, including keyword research, backlinks, competitor analysis, and on-page audits.224-