Content
# aparser-mcp
**English** · [Русский](README.ru.md)
[](https://www.npmjs.com/package/aparser-mcp)
An [MCP](https://modelcontextprotocol.io) server that exposes the
[A-Parser](https://a-parser.com) 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](https://github.com/modelcontextprotocol/typescript-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:
```bash
AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npx -y aparser-mcp
```
<details>
<summary>Or run from source</summary>
```bash
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
```
</details>
## 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
```bash
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:
```json
{
"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`](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:
```json
[["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`](skills/aparser/examples.md).
## Companion skill (`aparser`)
The [`skills/aparser/`](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:
```bash
# 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`](skills/aparser/SKILL.md) and [`skills/aparser/api-reference.md`](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
```bash
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`](src/index.ts).
