aparser-mcp

English · Русский

An MCP server that exposes the A-Parser HTTP API as tools, so an AI agent can drive parsing tasks directly — run a SERP or suggest query, queue bulk jobs, poll them, and fetch results.

Transport: stdio. Built on the official TypeScript MCP SDK.

Requirements

• A running A-Parser instance with the API enabled (Settings → API) and its password. The API listens on http://<host>:9091/API.
• Node.js ≥ 18 (for npx, or to build from source).

Run

Published on npm — no install needed, npx fetches and runs it:

AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npx -y aparser-mcp

Or run from source

git clone <this-repo> aparser-mcp && cd aparser-mcp
npm install          # builds dist/ via the prepare script
AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npm start

Configure

The server reads three environment variables:

Variable	Required	Description
AP_URL	yes	API base URL, e.g. http://127.0.0.1:9091/API (a trailing /API is added if missing).
AP_PASSWORD	yes	API password from the A-Parser web UI.
AP_TIMEOUT	no	Per-request HTTP timeout in seconds (default 130).

Register with Claude Code

claude mcp add aparser \
  --env AP_URL=http://<host>:9091/API \
  --env AP_PASSWORD=<password> \
  -- npx -y aparser-mcp

Or add it to .mcp.json / your MCP client config:

{
  "mcpServers": {
    "aparser": {
      "command": "npx",
      "args": ["-y", "aparser-mcp"],
      "env": {
        "AP_URL": "http://<host>:9091/API",
        "AP_PASSWORD": "<password>"
      }
    }
  }
}

Usage — just ask

Once the server and the aparser skill are installed, ask in plain language and the skill picks the parser, geo, and output format for you:

• “aparser, find positions of domain.com for: query one, query two in Serbia” → SE::Google::Position on google.rs (gl=rs, hl=sr) → rank per query.
• “aparser, Google autocomplete for buy iphone” → suggestions.
• “aparser, top-20 Google results for best running shoes in Spain” → SERP links.

More concrete tool-call examples: skills/aparser/examples.md.

Tools

Tool	What it does
ping	Health check. Returns "pong".
info	Server status: tasks in queue, pid, list of available parsers.
list_parsers	Just the parser names (e.g. SE::Google, SE::Google::Suggest).
parser_info	A parser's result-field schema (arrays + flat) for building a resultsFormat.
get_proxies	Live proxies from the checkers as {"ip:port": ["type", ...]}.
one_request	Run one parse synchronously and return the result. Best for single lookups.
add_task	Queue a bulk task saved to a file. Returns the task id.
task_state	A task's status and live stats.
wait_task	Poll a task until it completes; returns the final state.
task_results	Single-use download URL for a completed task's results file.

one_request vs add_task

• one_request — synchronous, one query, result returned inline. Use it for a suggest lookup, a single SERP, checking one page.
• add_task — asynchronous queue, many queries, output written to a file on the server. Use wait_task then task_results to retrieve it.

Parser stack & resultsFormat

add_task takes a parsers stack — a list of [name, preset, ...overrides] entries:

[["SE::Google", "default"]]

In results_format, $p1 refers to the first entry, $p2 the second, etc. Call parser_info("SE::Google") to see the fields you can reference:

$p1.serp.format('$link; $anchor\n')

Per-request overrides (in one_request.options or a parsers entry) use the shape {"type": "override", "id": "<param_id>", "value": <value>}.

Examples

Copy-adaptable request examples — suggests, SERP, position checks with geo, captcha solving, desktop/mobile, bulk tasks — are in skills/aparser/examples.md.

Companion skill (aparser)

The skills/aparser/ directory holds a Claude Code skill that teaches an agent when and how to call these tools — parser naming, presets, geo, resultsFormat, and the position-checking query format. Install it so Claude picks it up:

# easiest — via skills.sh (installs into every supported agent):
npx skills add izzipizzy/aparser-mcp

# or manually as a personal Claude Code skill:
cp -r skills/aparser ~/.claude/skills/aparser

It then loads automatically when you ask about A-Parser positions/SERPs/suggests. (Inside the izzy plugin it is the izzy:aparser skill.) See skills/aparser/SKILL.md and skills/aparser/api-reference.md.

Notes

• Parsers that hit search engines need working proxies. If one_request hangs or errors, check get_proxies and the parser's proxy settings in A-Parser.
• Secrets are never stored in this repo. Keep AP_PASSWORD in your MCP client config or the environment.

Development

npm install     # install deps + build
npm run build   # compile src/ -> dist/
npm start       # run the built server (needs AP_URL / AP_PASSWORD)

Source is a single file: src/index.ts.