pline.ai API — Agent skill and MCP

Use the hosted pline.ai API from an agent skill or an MCP client. Both integrations use your own API key and call the same hosted scraping API. The scraping backend is not part of this repository.

| Integration | Contents | Requirements | |---|---|---| | pline-api skill | Agent instructions, API reference, Python CLI for scrape, batch, crawl, map, and search | Python 3.10+; no pip dependencies | | MCP server | Ten tools over local stdio; embedded usage guide and API reference | npx -y pline-api (Node.js 18+); also a Docker image, prebuilt binaries, or a Cargo source build | | n8n community node | n8n-nodes-pline: Scrape, Batch Scrape, Crawl, Map and Search operations for n8n workflows | n8n 1.x; install from n8n's community nodes panel |

Fastest setup: run npx -y pline-api@latest init and enter your API key. It configures every supported MCP client on your machine and installs the skill; see Quick install.

For remote agents, the MCP server also supports Streamable HTTP with Pline OAuth. Users sign in, choose a workspace API key, and connect at the hosted /mcp URL; see mcp-server/docs/oauth-hosting.md for setup.

Quick install

One command: init

Needs Node.js 18+. Run it in a terminal:

npx -y pline-api@latest init

init finds the MCP clients on your machine, shows what it will change, asks you to confirm, and asks for your pline.ai API key (input hidden; or set PLINE_API_KEY first). Then it:

| Client | What init does | Where the key is kept | |---|---|---| | Claude Code | claude mcp add pline-ai --scope user … | Claude Code's user config | | Codex | codex mcp add pline-api … | ~/.codex/config.toml | | Cursor | adds pline.ai to ~/.cursor/mcp.json | that file | | VS Code | adds pline.ai to your user mcp.json | not stored; VS Code asks on first start | | Claude Desktop | adds pline.ai to claude_desktop_config.json (macOS, Windows) | that file | | Windsurf | adds pline.ai to ~/.codeium/windsurf/mcp_config.json | that file |

It also installs the agent skill for those agents with skills.sh. Existing config files are merged, never replaced: other servers stay, a *.pline-backup-<time> copy is written first, and files that are not plain JSON (for example with comments) are left alone and reported. Restart your clients afterwards.

| Option | Effect | |---|---| | --agent <id> | Only this client; repeat for several: claude-code, codex, cursor, vscode, claude-desktop, windsurf | | --mcp-only / --skill-only | Set up just the MCP server, or just the skill | | --dry-run | Show what would change without changing anything | | --yes | Skip the confirmation (needed when not running in a terminal) | | --base-url <url> | Use another API base URL (default https://apix.pline.ai/v1) |

npx -y pline-api@latest init --agent cursor --agent claude-code   # only these clients
npx -y pline-api@latest init --dry-run                            # preview, change nothing
PLINE_API_KEY=your-key npx -y pline-api@latest init --yes         # non-interactive (scripts, CI)

Run init again at any time to change the key or add a newly installed client; it updates the existing pline entries in place. To remove pline.ai, delete the pline.ai / pline-ai / pline-api entry from each client (claude mcp remove pline-ai --scope user, codex mcp remove pline-api) and run npx skills remove pline-api -g.

npx -y pline-api on its own is the MCP server, not the installer: run by hand it only waits for an MCP client. Use init to set things up.

Install separately

To set up the two integrations by hand instead, use either or both of the following.

Agent skill (instructions plus a Python CLI the agent runs):

npx skills add grepsr/pline-api

This copies skills/pline-api from this GitHub repository into your agent's skills folder (Claude Code, Cursor, Codex, and more). skills is the skills.sh installer, not a pline package; the skill is not published to npm. Running it needs Python 3.10+ and PLINE_API_KEY in the agent's environment (PLINE_BASE_URL defaults to https://apix.pline.ai/v1); see Skill setup.

MCP server (ten tools for any MCP client):

npx -y pline-api

You do not run this yourself: add it to your MCP client's configuration below and the client starts it. It needs Node.js 18+ (or Docker).

The MCP server is the pline-api npm package, listed in the official MCP Registry as io.github.grepsr/pline-api, and also shipped as the ghcr.io/grepsr/pline-mcp image. Every MCP client takes the same configuration:

{
  "mcpServers": {
    "pline.ai": {
      "command": "npx",
      "args": ["-y", "pline-api"],
      "env": {
        "PLINE_BASE_URL": "https://apix.pline.ai/v1",
        "PLINE_API_KEY": "your-own-api-key"
      }
    }
  }
}

| Client | One step | |---|---| | Claude Code | claude mcp add pline-ai -e PLINE_BASE_URL=https://apix.pline.ai/v1 -e PLINE_API_KEY=your-own-api-key -- npx -y pline-api | | Claude Code plugin (skill + hosted server) | claude plugin marketplace add grepsr/pline-api then claude plugin install pline-ai@pline-ai; sign in with your pline.ai account on first use | | Cursor | then replace your-own-api-key in Cursor's MCP settings | | VS Code | ; VS Code prompts for the URL and key | | Codex (CLI, IDE extension, app) | codex mcp add pline-api --env PLINE_BASE_URL=https://apix.pline.ai/v1 --env PLINE_API_KEY=your-own-api-key -- npx -y pline-api; see Codex to keep the key out of the config file | | Windsurf, Claude Desktop, others | Paste the JSON above into the client's MCP configuration; see MCP setup for each file's location |

Opening this repository as a workspace configures the server automatically through .cursor/mcp.json and .vscode/mcp.json. PUBLISHING.md tracks every registry and directory listing.

Clone and configure for source builds or skills

git clone https://github.com/grepsr/pline-api.git
cd pline-api
cp .env.example .env

Edit .env: keep PLINE_BASE_URL=https://apix.pline.ai/v1 (the public pline.ai API) and set PLINE_API_KEY to your own key.

Load them before launching your agent or MCP client (POSIX shells):

set -a
. ./.env
set +a

Neither client loads .env automatically. On other platforms, set the same variables in your shell or client settings. Git ignores .env, local session files, and build output.

Skill setup

The pline-api skill teaches an agent how to choose an API operation, reuse scrape sessions, extract structured data, poll background jobs, and save results. It uses connected pline.ai MCP tools when available; otherwise it runs the bundled Python client. A skill-only installation requires Python 3.10+, Git, and a pline.ai API key; the API base URL is https://apix.pline.ai/v1. It does not require Rust, a compiled MCP binary, or pip packages.

npx -y pline-api@latest init installs the skill together with the MCP server (--skill-only for just the skill). To install the skill on its own, use the skills CLI, which copies the skill from this GitHub repository (not from npm) into the right folder for each agent it detects (add -g for a user-wide install, -a cursor to pick agents):

npx skills add grepsr/pline-api

To install by hand, copy the whole directory, not just SKILL.md:

pline-api/
├── SKILL.md                 # Instructions and when to use the skill
├── scripts/pline.py         # Python client
├── references/endpoints.md  # API fields, examples, and limits
└── agents/openai.yaml       # Codex display metadata

The agent needs permission to execute Python, reach your pline.ai API over HTTPS, and write to any output directory you request. Shell examples below use macOS, Linux, or WSL; native Windows instructions follow the client sections. These are local-agent installations. A cloud agent needs the skill, Python, network access, and credentials configured in its own execution environment.

| Client | Personal skill directory | Project-only directory | Invoke in agent chat | |---|---|---|---| | Claude Code | ~/.claude/skills/pline-api/ | <project>/.claude/skills/pline-api/ | /pline-api | | Codex | ~/.agents/skills/pline-api/ | <project>/.agents/skills/pline-api/ | $pline-api in CLI/IDE | | Cursor | ~/.cursor/skills/pline-api/ | <project>/.cursor/skills/pline-api/ | /pline-api | | DeepSeek through Claude Code | Same as Claude Code | Same as Claude Code | /pline-api |

Prepare credentials and Python

First complete Clone and configure, including loading .env in your shell. Run these commands from the cloned pline-api repository:

python3 --version
python3 skills/pline-api/scripts/pline.py --help
python3 -c 'import os; print({name: bool(os.environ.get(name)) for name in ("PLINE_BASE_URL", "PLINE_API_KEY")})'

The version must be 3.10 or later, help must list the API commands, and both environment checks must print True. The check prints only whether each value is present. --help does not contact the service; actual scrape, crawl, batch, map, and search requests use your API account.

Start the agent from this configured shell. An already-running desktop app may not inherit new variables. If necessary, configure them in the agent's execution environment or have the agent source your local .env in the same shell invocation that runs `pl