Pline.ai README

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.

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:

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.

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

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.

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 pline.py. Never paste an API key into an agent conversation. The Python client does not load .env automatically.

Claude Code

Install Claude Code and sign in if it is not already set up. For a personal installation, run from this repository root:

mkdir -p "$HOME/.claude/skills/pline-api"
cp -R skills/pline-api/. "$HOME/.claude/skills/pline-api/"
python3 "$HOME/.claude/skills/pline-api/scripts/pline.py" --help

Launch claude in the project where you want to save results, using the shell with your pline.ai variables loaded. Type /pline-api in the conversation and select the skill, for example:

/pline-api Scrape https://example.com as Markdown and save it under ./page-output.

Alternatively, install the skill and the hosted MCP server together as the pline-ai plugin (the plugin/ folder). It connects to https://mcp.pline.ai/mcp, and you sign in with your pline.ai account the first time Claude uses it, so no API key is stored in Claude:

claude plugin marketplace add grepsr/pline-api
claude plugin install pline-ai@pline-ai

For a project-only installation, replace the destination above with /absolute/path/to/your-project/.claude/skills/pline-api/, then start Claude Code in that project. If the skill does not appear, restart the session and confirm SKILL.md is directly inside that folder. Local personal folders do not automatically install the skill into Claude's web or Cowork sessions; those use account-managed skills. See the official Claude skill discovery documentation.

Codex

For a personal installation, run from this repository root:

mkdir -p "$HOME/.agents/skills/pline-api"
cp -R skills/pline-api/. "$HOME/.agents/skills/pline-api/"
python3 "$HOME/.agents/skills/pline-api/scripts/pline.py" --help

Open your working project in Codex. In the CLI or IDE extension, use /skills to find pline-api, or type $pline-api in your prompt:

$pline-api Extract the product name and price from https://example.com/product as JSON.

In the desktop interface, select the installed skill from its skills picker; the current ChatGPT interface uses @ to attach skills. Set the pline.ai variables in the environment where its shell tools run. For a project-only installation, copy the directory to /absolute/path/to/your-project/.agents/skills/pline-api/ and open that project. Restart Codex if newly copied files are not discovered. These local paths and invocation methods are documented in OpenAI's skill guide.

Cursor

For a personal installation, run from this repository root:

mkdir -p "$HOME/.cursor/skills/pline-api"
cp -R skills/pline-api/. "$HOME/.cursor/skills/pline-api/"
python3 "$HOME/.cursor/skills/pline-api/scripts/pline.py" --help

Open your working project in Cursor and use Agent chat. Type / and select pline-api, then ask:

/pline-api Read urls.txt, scrape those URLs as a batch in Markdown, and save the completed results under ./batch-output.

Use /absolute/path/to/your-project/.cursor/skills/pline-api/ instead for a project-only install. Restart Cursor if needed and verify that its agent terminal can see the pline.ai variables. Cursor also discovers .agents/skills and Claude-compatible skill directories, so check for an existing pline-api before making another copy. Its official skill guide describes these locations and invocation. The Skills panel lists discovered skills. These copy commands install the skill directly; this repository is not packaged as a Cursor marketplace plugin.

For the MCP server in Cursor, either use the Add to Cursor button under Quick install (Docker image, any project) or open this repository as a workspace: .cursor/mcp.json runs the source build and reads PLINE_BASE_URL and PLINE_API_KEY from Cursor's environment.

DeepSeek through Claude Code

Here DeepSeek supplies the model and Claude Code runs the skill and Python commands. Follow the Claude Code installation above, then configure the provider using DeepSeek's official integration guide. This route does not install a skill into the DeepSeek browser chat.

You need two separate credentials: a DeepSeek API key for the model and PLINE_API_KEY for scraping. Keep PLINE_BASE_URL pointing at your pline.ai API. In a new terminal, load your pline.ai .env, then configure the model provider:

export ANTHROPIC_BASE_URL='https://api.deepseek.com/anthropic'
export ANTHROPIC_AUTH_TOKEN='your-deepseek-api-key'
export ANTHROPIC_MODEL='deepseek-flash[1m]'
export ANTHROPIC_DEFAULT_OPUS_MODEL='deepseek-flash[1m]'
export ANTHROPIC_DEFAULT_SONNET_MODEL='deepseek-flash[1m]'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='deepseek-flash'
export CLAUDE_CODE_SUBAGENT_MODEL='deepseek-flash'
export CLAUDE_CODE_EFFORT_LEVEL='max'
claude

Replace the key placeholder locally. Model names above follow DeepSeek's guide as checked on 2026-09-17; consult that guide if the provider changes them. These exports affect this shell and processes launched from it. Invoke the same installed skill:

/pline-api Map https://example.com and show me up to 20 discovered URLs.

For another DeepSeek-powered agent, use that host's Agent Skills installation path and credential settings. The model API alone does not provide the local Python execution environment.

Native Windows / PowerShell

Run from the cloned repository. Set the variables for this PowerShell session; replace the key placeholder with your pline.ai key (PLINE_BASE_URL is optional and defaults to this URL):

$env:PLINE_BASE_URL = 'https://apix.pline.ai/v1'
$env:PLINE_API_KEY = 'your-pline-api-key'
python --version
python skills/pline-api/scripts/pline.py --help

Choose one destination for the client you are installing into:

# Claude Code, including the DeepSeek-through-Claude-Code setup:
$plineSkillDir = Join-Path $HOME '.claude/skills/pline-api'
# Codex: use this assignment instead.
# $plineSkillDir = Join-Path $HOME '.agents/skills/pline-api'
# Cursor: use this assignment instead.
# $plineSkillDir = Join-Path $HOME '.cursor/skills/pline-api'

New-Item -ItemType Directory -Force -Path $plineSkillDir | Out-Null
Copy-Item -Path 'skills/pline-api/*' -Destination $plineSkillDir -Recurse -Force
python (Join-Path $plineSkillDir 'scripts/pline.py') --help

For a project-only install, set $plineSkillDir to the corresponding .claude, .agents, or .cursor path inside that project. Launch the client from the configured session. If Python is available as py rather than python, use py -3 in these examples and tell the agent which interpreter to use. Keep installations and credentials inside WSL when the agent runs in WSL.

For DeepSeek, translate each provider export above to PowerShell syntax before launching claude, for example $env:ANTHROPIC_BASE_URL = 'https://api.deepseek.com/anthropic' and $env:ANTHROPIC_MODEL = 'deepseek-flash[1m]'. The other variable names and values stay the same.

Verify the installed skill

After copying, set PLINE_SKILL_DIR to your chosen installation directory, for example:

PLINE_SKILL_DIR="$HOME/.agents/skills/pline-api"
python3 "$PLINE_SKILL_DIR/scripts/pline.py" --help
python3 "$PLINE_SKILL_DIR/scripts/pline.py" scrape \
  --url https://example.com --output markdown --save ./pline-check

The second command makes a real API request. With working credentials it should create ./pline-check/markdown.md when the page returns Markdown. On Windows, run the same arguments with python (Join-Path $plineSkillDir 'scripts/pline.py').

Then invoke the skill in your agent and request one page. Confirm it calls a pline.ai MCP tool or runs the installed scripts/pline.py. If MCP is not configured, ask it to use the Python client. Files are saved relative to the agent's working project, not the skill installation directory.

Example tasks and expected results

Prefix these requests with your client's invocation from the table above:

The Python client and local stdio MCP can save files. HTTP MCP rejects save_dir and download_dir; for that transport, use returned content or artifact links, or the Python client for local downloads. Repeated requests to a site should reuse the MCP's remembered scrape session or a CLI --session-file. For background jobs, keep the returned UUID so you can resume polling or cancel the correct job.

Update or remove an installed skill

Run git pull --ff-only in your clone, then rerun the copy commands for your chosen client. The skills/pline-api/. source copies the contents into the existing destination without creating a nested pline-api/pline-api directory. Copying updates existing files but does not remove obsolete ones; for a clean replacement, move your old installed directory aside and copy into a new one. Keep customizations in your backup and reload the agent after an update. Copy-based installations do not update themselves when the source repository changes.

To uninstall, remove only the installed pline-api directory from the selected personal or project skill location and reload the agent. Your source clone, outputs, and MCP configuration are separate.

Troubleshooting

Direct CLI use

No skill installation is needed to run the client yourself:

python3 skills/pline-api/scripts/pline.py scrape --url https://example.com --output markdown
python3 skills/pline-api/scripts/pline.py batch start --urls-file urls.txt --output markdown
python3 skills/pline-api/scripts/pline.py crawl start --url https://example.com --limit 20
python3 skills/pline-api/scripts/pline.py map --url https://example.com --limit 100
python3 skills/pline-api/scripts/pline.py serp --query 'example search' --mode fast

Use --help on any command for flags. For wire-level examples, see the skill's API reference.

Download the MCP binary

Download a prebuilt binary from pline.ai MCP v0.3.9 using the links below. No Rust installation is needed. See GitHub Releases for all versions.

Download SHA256SUMS and compare the archive's SHA-256 hash with its line in that file: use shasum -a 256 FILE on macOS, sha256sum FILE on Linux, or Get-FileHash FILE -Algorithm SHA256 in PowerShell. Extract the archive into a permanent folder and use the executable's absolute path in the MCP configuration below. Windows uses pline-mcp.exe; macOS and Linux use pline-mcp.

MCP setup

npx -y pline-api@latest init does everything in this section for you (see Quick install). The per-client steps below are for manual setup.

The server runs locally as a stdio process that your MCP client starts; it calls the hosted pline.ai API over HTTPS with your key. npx -y pline-api downloads the pline-api launcher, which picks the prebuilt binary for your platform (macOS arm64/x64, Linux x64/arm64, Windows x64). Node.js 18 or newer is the only requirement. https://apix.pline.ai/v1 is the public pline.ai API; replace your-own-api-key with your key and keep real keys in the client's local settings, never in a committed file.

Cursor

Click Add to Cursor under Quick install, or open Cursor Settings → MCP → Add new global MCP server and paste:

{
  "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"
      }
    }
  }
}

Project-level configuration lives in .cursor/mcp.json; this repository ships one that reads the two variables from Cursor's environment. On Windows, if npx is not found, use "command": "cmd", "args": ["/c", "npx", "-y", "pline-api"].

Windsurf

Add the same mcpServers entry to ~/.codeium/windsurf/mcp_config.json.

VS Code

Click Install in VS Code under Quick install, or add to your user settings or to .vscode/mcp.json in a workspace (this repository ships one). VS Code prompts for the values and masks the key:

{
  "inputs": [
    { "type": "promptString", "id": "pline-base-url", "description": "pline.ai API base URL" },
    { "type": "promptString", "id": "pline-api-key", "description": "pline.ai API key", "password": true }
  ],
  "servers": {
    "pline.ai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pline-api"],
      "env": {
        "PLINE_BASE_URL": "${input:pline-base-url}",
        "PLINE_API_KEY": "${input:pline-api-key}"
      }
    }
  }
}

Claude Desktop

Add the mcpServers entry from Cursor to claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude Desktop.

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

Or install the skill together with the hosted server as the pline-ai plugin. It connects to https://mcp.pline.ai/mcp, and you sign in with your pline.ai account (OAuth) on first use instead of storing an API key:

claude plugin marketplace add grepsr/pline-api
claude plugin install pline-ai@pline-ai

Inside this repository, .mcp.json runs the server from source through Cargo instead, for development.

Codex

The Codex CLI, IDE extension, and app share ~/.codex/config.toml (or .codex/config.toml in a trusted project). Add the server with one command:

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

That writes the key into config.toml. To keep it there only as a name, edit the file instead and let Codex forward PLINE_API_KEY from the environment it starts in (Codex does not pass its environment to MCP servers unless a variable is listed in env_vars):

[mcp_servers.pline-api]
command = "npx"
args = ["-y", "pline-api"]
env_vars = ["PLINE_API_KEY"]

[mcp_servers.pline-api.env]
PLINE_BASE_URL = "https://apix.pline.ai/v1"

Check it with codex mcp list. To use the hosted server with OAuth instead, add this repository's plugin (codex plugin marketplace add grepsr/pline-api, then codex plugin add pline-ai@pline-ai) and sign in with codex mcp login pline.ai; it brings the skill along.

Docker

Every release is also a multi-platform image (linux/amd64, linux/arm64) at ghcr.io/grepsr/pline-mcp. Use it where Node.js is unavailable or containers are preferred:

{
  "mcpServers": {
    "pline.ai": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PLINE_BASE_URL", "-e", "PLINE_API_KEY",
               "ghcr.io/grepsr/pline-mcp:0.3.9", "--stdio"],
      "env": {
        "PLINE_BASE_URL": "https://apix.pline.ai/v1",
        "PLINE_API_KEY": "your-own-api-key"
      }
    }
  }
}

-e NAME without a value forwards each variable from the environment the client sets, so the key stays out of the command line. The container cannot see your filesystem, so save_dir and download_dir need a volume mount. Pin a release tag rather than latest. Details are in the server README.

Prebuilt binary or source build

Download the MCP binary and point the client at its absolute path with "command": "/absolute/path/to/pline-mcp", "args": ["--stdio"] (pline-mcp.exe on Windows). The npm launcher also honours PLINE_MCP_BINARY=/path/to/pline-mcp to run a binary you built yourself:

cargo build --manifest-path mcp-server/Cargo.toml --release --locked

The executable is pline-mcp; its public MCP identity is pline.ai. Streamable HTTP mode is npx -y pline-api --http 127.0.0.1:8080; see HTTP mode.

Update and verify

npx -y pline-api resolves the latest published version on each start, so npm installs need no action; pin pline-api@<version> in the client configuration if you want to control upgrades. To change your API key or add a client you installed later, run npx -y pline-api@latest init again. For a prebuilt installation, download the new release, verify its checksum, and replace the installed executable. Reconnect your MCP client after updating.

For source installations, pull updates and rebuild; refresh any installed skill copies:

git pull --ff-only
cargo build --manifest-path mcp-server/Cargo.toml --release --locked

Development checks:

cargo fmt --manifest-path mcp-server/Cargo.toml -- --check
cargo clippy --manifest-path mcp-server/Cargo.toml --locked --all-targets --all-features -- -D warnings
cargo test --manifest-path mcp-server/Cargo.toml --locked
cargo build --manifest-path mcp-server/Cargo.toml --locked
python3 tests/smoke.py

The smoke check uses a localhost mock API and dummy credentials to exercise the skill, stdio, and HTTP transports. HTTP is stateless and rejects local file output options; local Git installs use stdio and support saving files. See HTTP mode for transport details.

Build, release, and publish

Build release binaries builds and tests all four platforms and builds the Docker image. Run it manually from a branch in the Actions tab to check builds without creating a release or pushing an image. It needs no API keys or extra repository secrets.

When ready to release, bump the version everywhere python3 tests/check_versions.py looks (mcp-server/Cargo.toml, server.json, plugin/.claude-plugin/plugin.json, .claude-plugin/marketplace.json, and the pinned image tags in the READMEs), then push a version tag such as v0.1.0. The tag must exactly match the Cargo version with a v prefix. After every platform passes unit and MCP/skill smoke tests, the workflow pushes ghcr.io/grepsr/pline-mcp:<version> and :latest for amd64 and arm64, then creates a draft GitHub Release containing all four archives and SHA256SUMS. Review the draft and publish it manually. Reruns can refresh draft assets; they refuse to replace assets on an already published release.

Publishing the release triggers Publish release, which builds the per-platform npm packages from the release archives, publishes them and the pline-api launcher to npm, then publishes server.json to the official MCP Registry with GitHub OIDC. PUBLISHING.md covers that flow, the credentials involved, and the Claude directory, Cursor, VS Code, Glama, and community list submissions.

License

MIT. Copyright (c) 2026 Grepsr.